<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<meta name="description" content="This chapter contains a functional overview of the high-performance GUIX user interface product.">
<title>Chapter 3 - Functional Overview of GUIX</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.square{list-style-type:square}
ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="article">
<div id="header">
<h1>Chapter 3 - Functional Overview of GUIX</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This chapter contains a functional overview of the high-performance GUIX
user interface product.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_execution_overview">Execution Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>GUIX implements an event driven programming model. This means that the
GUIX framework is primarily driven by the receipt of events pushed into
the GUIX event queue. The processing of these events takes place in the
context of the GUIX thread, which is a ThreadX thread created during
GUIX system initialization.</p>
</div>
<div class="paragraph">
<p>GUIX applications define the user interface by calling GUIX API
functions to create windows and child widgets, and customize the
appearance of these widgets by calling additional API functions used to
define colors, styles, fonts, and various other attributes of each
window or widget type. If you are using GUIX Studio to create the
appearance of your user-interface screens, much of this work of calling
GUIX API functions to create your display is done for you by the GUIX
Studio application.</p>
</div>
<div class="paragraph">
<p>GUIX applications interact with the system user and with external
business logic by handling events retrieved from the GUIX event queue.
These events are usually produced by GUIX widgets, but they can also be
created by external threads. When a typical GUIX button is pushed, that
button sends an event to the button&#8217;s parent window. Your application
program will act on that button push by providing a handler for the
button push event.</p>
</div>
<div class="paragraph">
<p>Additional GUIX threads are often created for things such as input
drivers. A typical touch screen input driver is executed as a standalone
thread external to the main GUIX thread. The touch input driver sends
touch information into the GUIX thread by sending events into the GUIX
event queue.</p>
</div>
<div class="paragraph">
<p>Since many user-interface operations such as animations require accurate
timing information, GUIX also implements a simple and easy to use timer
interface. This timer interface is built upon the ThreadX timer service,
and is configured automatically at system startup.</p>
</div>
<div class="paragraph">
<p>The vast majority of the GUIX software is independent of any hardware
dependencies. The framework does require hardware-specific input drivers
and hardware-specific graphics drivers. The details of how these
hardware specific drivers are implemented are deferred to chapter 5.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_initialization">Initialization</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The service <strong><em>gx_system_initialize</em></strong> must be called before any other
GUIX service is called. GUIX system initialization can be called from
the ThreadX <strong><em>tx_application_define</em></strong> routine (initialization
context) or from application threads. The <strong><em>gx_system_initialize</em></strong>
function creates the GUIX event queue, initializes the GUIX timer
facility, creates the main GUIX system thread, and initializes various
data structures maintained by GUIX during the execution of your
application.</p>
</div>
<div class="paragraph">
<p>After <strong><em>gx_system_initialize</em></strong> returns, the application is ready to
create displays, canvases, windows, widgets, and customize the
properties of all GUIX objects. Much of the GUIX object creation API can
be called from <strong><em>tx_application_define</em></strong> or from application
threads.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_application_interface_calls">Application Interface Calls</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Calls from the application are largely made from
<strong><em>tx_application_define</em></strong> (initialization context) or from
application threads. Please see the "Allowed From" section of each GUIX
API described in Chapter 4 to determine what context it may be called
from.</p>
</div>
<div class="paragraph">
<p>For the most part, processing intensive activities are deferred to the
internal GUIX thread, including all event processing and widget/window
drawing.</p>
</div>
<div class="paragraph">
<p>The GUIX API functions can be called from any thread, with the exception of timer threads or interrupts. The reason for this restriction is to prevent blocking of the timer thread, as certain GUIX APIs have the potential to block the thread while acquiring a mutex. This can also be problematic if the request originates from an interrupt, as it may lead to protection failure.</p>
</div>
<div class="paragraph">
<p>Nevertheless, it is usually considered to be better architecture to separate
your time-critical business logic from your user interface logic. Since
the user interface drawing operations can sometimes take a long time
depending on your display size and CPU performance, you normally would
not want to have time-critical threads delayed waiting for a drawing
operation to complete.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_internal_guix_thread">Internal GUIX Thread</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As mentioned, GUIX has an internal thread that performs the bulk of the
GUI processing. This thread is created by the application software by
calling <strong><em>gx_system_initialize</em></strong> followed by <strong><em>gx_system_start</em></strong>.</p>
</div>
<div class="paragraph">
<p>The priority of the internal GUIX thread is determined by the <code>#define GX_SYSTEM_THREAD_PRIORITY</code>. This value defaults to 16 (middle
priority) but can be modified by specifying this value in the gx_port.h or gx_user.h header file, overriding the default value.</p>
</div>
<div class="paragraph">
<p>The GUIX thread time slice is similarly defined by the <code>#define GX_SYSTEM_THREAD_TIMESLICE</code>, which defaults to the value 10 ms.</p>
</div>
<div class="paragraph">
<p>The stack size of the system thread is determined by the <code>#define GX_THREAD_STACK_SIZE</code>, which is found in the <strong><em>gx_port.h</em></strong> header file,
but can also be overridden by specifying this value in your gx_user.h
header file.</p>
</div>
<div class="paragraph">
<p>The internal GUIX thread execution loop is composed of three actions.
First, GUIX retrieves events from the GUIX event queue and dispatches
those events for processing by the GUIX windows and widgets. Events are
typically pushed into the GUIX event queue by periodic timers, input
devices such as a touch screen or keypad, and by GUIX widgets themselves
as they process user input. Next, after all events have been processed,
GUIX determines if a screen refresh is needed, and if so performs the
processing necessary to update the display graphics data, mainly by
calling the drawing functions of those windows and widgets which have
been marked as dirty. Finally, GUIX suspends the GUIX thread until a new
input event or events arrive.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_event_processing">Event Processing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Touch or pen input events are processed by determining the top-most
window or widget beneath the touch or pen input pixel position and
calling that window/widget&#8217;s event processing function. If the widget
understands pen input events, it will process the event as appropriate
for that widget type. If not, the top-most widget will pass the touch or
pen input event to the widget&#8217;s parent for processing. This passing of
the event up the chain continues until either the event is handled or
the event arrives at the root window, in which case the event is
discarded.</p>
</div>
<div class="paragraph">
<p>Keypad events are sent to the window/widget that has input focus. Input
focus status is maintained by the GUIX gx_system component.</p>
</div>
<div class="paragraph">
<p>Timer events are always dispatched to the window or widget that owns the
timer for processing.</p>
</div>
<div class="paragraph">
<p>Internally generated events, such as button click events or slider value
change events, are always sent to the parent of the widget generating
the event. If the parent does not process the event, it is passed up the
chain similar to touch or pen input events.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_drawing">Drawing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Once all the event processing is complete, the GUIX internal thread
determines if any display update is needed and if so the appropriate
window/widget drawing functions are called. When drawing is complete,
the GUIX internal thread simply waits on its event queue for the next
GUIX event to process.</p>
</div>
<div class="paragraph">
<p>GUIX implements the concept of <em>dirty areas</em>, which are areas that need to be re-drawn, for each widget and canvas. A widget can only draw to areas that have previously been marked as dirty. When a widget drawing function is called, all drawing operations are internally clipped to the previously defined dirty rectangle.
Attempts to draw outside of this area are ignored.</p>
</div>
<div class="paragraph">
<p>Widgets and windows mark themselves as dirty by calling the API function <strong><em>gx_system_dirty_mark</em></strong>. This function marks the entire widget or
window as needing to be redrawn. A second function, <strong><em>gx_system_dirty_partial_add</em></strong>, can be invoked as an alternative to mark only a portion of a window or widget as dirty.</p>
</div>
<div class="paragraph">
<p>This model of marking widgets as dirty and then redrawing those widgets only when all input events have been processed is referred to as <em>deferred drawing</em>. The GUIX deferred drawing algorithm and dirty list maintenance is designed to improve drawing efficiency. Since drawing operations are typically expensive, GUIX works hard to prevent unnecessary drawing.</p>
</div>
<div class="paragraph">
<p>Drawing is done to a GUIX <em>canvas</em>. A canvas is a memory area
reserved to hold graphics data. A canvas may or may not be directly
linked to the hardware frame buffer, depending on the system
architecture and memory constraints. Before any drawing can occur, a
canvas must first be opened for drawing by calling the
<strong><em>gx_canvas_drawing_initiate</em></strong> API function. This API prepares a canvas
for drawing and established the current <em>drawing context</em>. When GUIX
performs a system canvas refresh, the canvas is opened for drawing and
the drawing context established before the widget-level drawing APIs are
invoked. Therefore widgets do not need to initiate drawing on a canvas
within the widget drawing function.</p>
</div>
<div class="paragraph">
<p>However, if an application desires to perform immediate drawing to a
canvas, outside the flow of the standard GUIX deferred drawing
algorithm, the application must directly invoke the
<strong><em>gx_canvas_drawing_initiate</em></strong> prior to calling any other drawing API functions,
and must call <strong><em>gx_canvas_drawing_complete</em></strong> once the immediate drawing
has been completed.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_user_input">User Input</h2>
<div class="sectionbody">
<div class="paragraph">
<p>GUIX supports touch screen, mouse, and keyboard devices with predefined
event types. Additional input devices can be utilized by defining custom
event types, or by mapping the custom input device to the predefined
event types.</p>
</div>
<div class="paragraph">
<p>Actions associated with these devices are translated into events that
are processed by the internal GUIX thread. Driver level software written
to support a touch screen must prepare and send to the GUIX event queue
events for pen-down, pen-up, and pen-drag operations. Similarly a keypad
input driver must generate events for key press and key release input.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_modal_dialog_execution">Modal Dialog Execution</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Modal dialog execution refers to presenting a window to the user that
must be closed in some way before any other GUIX windows or widgets can
receive user input. Modal dialogs capture all user input while the
dialog window is displayed, regardless of the x,y position of touch or
mouse input events.</p>
</div>
<div class="paragraph">
<p>Modal dialogs are triggered by the application software by first
creating the window in the normal way by calling
<strong><em>gx_window_create</em></strong>, and then calling the GUIX API function
<strong><em>gx_window_execute.</em></strong></p>
</div>
<div class="paragraph">
<p>When the <strong><em>gx_window_execute</em></strong> function is called, GUIX enters a
local event processing loop. The <strong><em>gx_window_execute</em></strong> function does
not return to the caller until the dialog window is closed, either by
user input or by calling <strong><em>gx_window_close</em></strong>. For this reason, it is
very important never to call the <strong><em>gx_window_execute</em></strong> function from
any thread other than the GUIX internal thread.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_periodic_processing">Periodic Processing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In order to provide display effects, sprite animation, and support for
application periodic requests, GUIX uses one ThreadX timer. This single
timer is used to drive all GUIX time-related needs. By default, the
frequency for the GUIX internal timer processing is set to 20ms via the
constant <strong>GX_SYSTEM_TIMER_MS</strong>, which is defined in <strong><em>gx_api.h</em></strong>,
unless the constant is previously defined in gx_port.h or gx_user.h
header. The default frequency may be changed by the application via a
compilation option when building the GUIX library or by explicitly
redefining it in <strong><em>gx_user.h</em></strong>.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Note that the GUIX timer frequency is expressed in RTOS timer ticks, and is defined by the constant <strong>GX_SYSTEM_TIMER_TICKS</strong>. The value of <strong>GX_SYSTEM_TIMER_TICKS</strong> is calculated using <strong>GX_SYSTEM_TIMER_MS</strong> and <strong>TX_TIMER_TICKS_PER_SECOND</strong>. The user can re-define any of these
values in the <strong><em>gx_port.h</em></strong> or <strong><em>gx_user.h</em></strong> to adjust the GUIX timer frequency and resolution.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_display_driver">Display Driver</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Display drivers are responsible for providing a set of drawing functions
to the core GUIX code. The implementation of each of these drawing
functions is determined by the driver, and when possible the
implementation will leverage hardware acceleration support. In general
the drawing function works by writing pixel data to a memory buffer,
which may be the physical frame buffer or it may be a secondary buffer
depending on the driver architecture. Many drivers implement double
buffering using two frame buffers, and these buffers are toggled by
invoking the buffer toggle function. GUIX calls these functions
internally at the appropriate times. For memory constrained systems, the
drawing functions may only write to a single memory frame buffer.</p>
</div>
<div class="paragraph">
<p>GUIX provides default software implementations of each low-level drawing
function at every support color depth and format. These functions are
invoked via function pointers maintained within the <strong>GX_DISPLAY</strong>
structure. When hardware-specific drivers are created, they typically
will overwrite some number of these function pointers with functions
that are specific to the target hardware.</p>
</div>
<div class="paragraph">
<p>A typical hardware display driver is implemented by first creating the
default GUIX display driver for the required color depth and format.
Then the hardware driver will replace those functions that need to be
optimized or customized for the particular hardware implementation.</p>
</div>
<div class="paragraph">
<p>GUIX support pixel color formats ranging from 1-bpp monochrome to 32-bpp
a:r:g:b format. GUIX also supports many variations within each broad
color-depth category, such as r:g:b versus b:g:r byte order, packed
pixel versus word-aligned pixel formats, and alpha channels. There are
currently 25 distinct color formats supported, but this list grows as
hardware vendors deliver new variations.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_display_memory_architectures">Display Memory Architectures</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Various hardware targets and displays utilize a variety of different
display memory architectures, depending on the memory constraints of the
target and the functionality requirements of the application. We will
outline some of the common memory architectures here with a brief
description of each.</p>
</div>
<div class="paragraph">
<p>Model 1) No frame buffer, graphics data held in external GRAM:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/no-frame-buffer.png" alt="No frame buffer" width="graphics data held in external GRAM">
</div>
</div>
<div class="paragraph">
<p>In the model above, no memory for a frame buffer exists in memory local
to the CPU. All graphics data is stored in an external GRAM which is
incorporated into the display itself. The interface to the external GRAM
can be parallel or serial. This type of architecture is very low cost;
however it can exhibit unwanted tearing effect when the graphics data is
updated.</p>
</div>
<div class="paragraph">
<p>Model 2) One local frame buffer:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/one-local-frame-buffer.png" alt="One local frame buffer">
</div>
</div>
<div class="paragraph">
<p>In this model, memory for the graphics data is allocated from a
random-access memory that is directly accessible the CPU. Dedicated
hardware must be present to repeatedly transmit the graphics data (along
with timing signals) from the local memory to the display. This model
differs from model 1 in that the graphics memory is a block of the local
SRAM or DRAM available to the CPU. This may be the same memory in which
stack and program variables live.</p>
</div>
<div class="paragraph">
<p>Model 3) Local frame buffer + external GRAM:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/local-frame-buffer-external-gram.png" alt="Local frame buffer + external GRAM">
</div>
</div>
<div class="paragraph">
<p>Model 3 is a combination of the first two. In this model, sufficient
local memory exists to hold one frame buffer. In addition, the display
device provides an external GRAM and automatically refreshes itself
using the data provided in the GRAM. This architecture benefits from
improved update efficiency because we can transfer the modified portion
of the local frame buffer to the external GRAM in one block transfer,
often utilizing onboard DMA channels. This model also eliminates the
tearing and flicker that can be present in either of the first two
models, because only completed graphics contents is copied to the
external GRAM.</p>
</div>
<div class="paragraph">
<p>Model 4) Ping-pong frame buffers:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/ping-pong-frame-buffers.png" alt="Ping-pong frame buffers">
</div>
</div>
<div class="paragraph">
<p>In model 4, sufficient memory is present to provide two local frame
buffers. In this case, GUIX treats one frame buffer as the active frame
buffer, and the other as the working frame buffer. When a display update
or drawing operation is in progress, it takes place in the working
buffer. When the drawing operation completes, the buffers are toggled,
and the working buffer becomes the active buffer and the active buffer
becomes the working buffer. This model also eliminates screen flicker
and tearing that can be observed in a single buffered system.</p>
</div>
<div class="paragraph">
<p>Model 5) Ping-pong buffers with canvas compositing:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/ping-pong-buffers-canvas-composting.png" alt="Ping-pong buffers with canvas compositing">
</div>
</div>
<div class="paragraph">
<p>In model 5, any number of canvases can be created, up to the limits of
available memory. The canvases can be overlaid or blended together as
defined by the application to create the canvas composite. When a new
composite is created after a screen refresh operation, the active and
working composite buffers are toggled in an operation identical to the
standard ping-pong buffer architecture. Model 5 adds the ability to
perform screen fade and blending operations by blending the canvases
into the final output composite.</p>
</div>
<div class="paragraph">
<p>Model 6) Canvas compositing with external GRAM:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/canvas-compositing-external-gram.png" alt="Canvas compositing with external GRAM">
</div>
</div>
<div class="paragraph">
<p>Model 6 is a slight variation on Model 5, in which only one composite
buffer is required and the composite buffer is then transferred to
external GRAM. This model also supports full screen blending and
overlays.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_string_encoding">String Encoding</h2>
<div class="sectionbody">
<div class="paragraph">
<p>GUIX by default supports UTF8 format string encoding. Support for UTF8 string encoding can be disabled by defining <strong>GX_DISABLE_UTF8_SUPPORT</strong>
in the <strong><em>gx_user.h</em></strong> header file. If UTF8 encoding is disabled, GUIX will internally use only standard 8-bit ASCII plus Latin-1 code page
character encoding. Disabling UTF8 string encoding results in a slightly smaller GUIX library footprint and slightly faster runtime execution of
string handling and text drawing functions.</p>
</div>
<div class="paragraph">
<p>UTF8 string encoding has the following traits:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ASCII strings take no more storage space than standard 7-bit ASCII
encoding.</p>
</li>
<li>
<p>Most ANSI-C string functions work with UTF8 string encoding without
modification.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>All active character sets in the world, including Kanji character sets, can be represented using UTF8 string encoding.</p>
</div>
<div class="sect2">
<h3 id="_static_and_dynamic_strings">Static and Dynamic Strings</h3>
<div class="paragraph">
<p>The strings assigned to your GUIX widgets which support text display can
be statically defined string constants, which are normally placed in
constant storage as part of the GUIX String table described below, and
dynamically defined strings, which are strings generated at runtime
using services such as <strong><em>sprintf</em></strong> or <strong><em>gx_utility_ltoa</em></strong>.</p>
</div>
<div class="paragraph">
<p>Examples of dynamic strings might include a value displayed as a number
within a GUIX prompt widget, or a "time / date" string which is dynamically
formatted based on the user&#8217;s location and format preferences. If you
create strings at runtime which will be assigned to GUIX widgets such as
<strong>GX_PROMPT</strong> or <strong>GX_TEXT_BUTTON widgets</strong>, you must choose to either
statically allocate the storage for these runtime generated strings (i.e
global character arrays), or you can define and install a dynamic memory
allocator function and use the <strong>GX_STYLE_TEXT_COPY</strong> style, which
instructs those widgets to create a private copy of text strings
assigned.</p>
</div>
<div class="paragraph">
<p>It is a programming error to use temporary storage, such as an automatic
character array, to hold a dynamically generated string and then assign
this string to a widget that does not have the <strong>GX_STYLE_TEXT_COPY</strong>
style. When this style is not enabled, the widget simply copies the
provided string pointer, and the string data must be statically
allocated or the widget string pointer will likely end up pointing at
garbage data producing unpredictable results.</p>
</div>
</div>
<div class="sect2">
<h3 id="_passing_gx_string_arguments">Passing GX_STRING arguments</h3>
<div class="paragraph">
<p>The GUIX API functions which accept a GX_STRING parameter always verify that the length of the string pointed to by the <strong>GX_STRING.gx_string_ptr</strong> field match the value of the <strong>GX_STRING.gx_string_length</strong> field. If the two fields are not consistent, a <strong>GX_INVALID_STRING_LENGTH</strong> error is returned and the API called returns without accepting the string assignment.</p>
</div>
<div class="paragraph">
<p>For safety considerations the GUIX software never internally uses the standard C string functions such as <strong><em>strlen</em></strong> or <strong><em>strcpy</em></strong>. These functions
have been known to be susceptible to malicious attacks when string data is acquired dynamically which is often the case with connected applications.</p>
</div>
<div class="paragraph">
<p>GUIX library releases prior to release 5.6 defined API functions which accepted (<code>GX_CONST GX_CHAR *text</code>) as a parameter. These functions, while still supported for backwards compatibility, have been obsoleted and replaced by the preferred API functions which accept (<code>GX_CONST GX_STRING *string</code>) as an input parameter.</p>
</div>
<div class="paragraph">
<p>By default, the deprecated text handling API is enabled allowing all previously written applications to build cleanly with the latest updates to the GUIX library. To disable the deprecated text handling API, the definition <strong>GX_DISABLE_DEPRECATED_STRING_API</strong> should be added to the <strong><em>gx_user.h</em></strong> header file. All new applications should define <strong>GX_DISABLE_DEPRECATED_STRING_API</strong> and should use only the replacement API functions. All output files generated by GUIX Studio for GUIX library version release 5.6 or later will utilize only the replacement API functions.</p>
</div>
<div class="paragraph">
<p>The following table lists the deprecated and newly defined replacement API function names:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top"><strong>Deprecated Function Name</strong></th>
<th class="tableblock halign-left valign-top"><strong>Replaced With</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_binres_language_table_load</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_binres_language_table_load_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_canvas_rotated_text_draw</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_canvas_rotated_text_draw_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_canvas_text_draw</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_canvas_text_draw_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_context_string_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_context_string_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_language_table_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_language_table_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_language_table_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_language_table_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_string_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_string_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_string_table_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_display_string_table_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_button_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_button_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_input_char_insert</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_input_char_insert_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_input_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_input_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_view_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_multi_line_text_view_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_prompt_text_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_prompt_text_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_prompt_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_prompt_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_single_line_text_input_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_single_line_text_input_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_system_string_width_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_system_string_width_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_system_version_string_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_system_version_string_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_button_text_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_button_text_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_button_text_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_button_text_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_scroll_wheel_callback_set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_text_scroll_wheel_callback_set_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_utility_string_to_alphamap</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_utility_string_to_alphamap_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_string_get</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_string_get_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_text_blend</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_text_blend_ext</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_text_draw</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">gx_widget_text_draw_ext</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_guix_string_table">GUIX String Table</h3>
<div class="paragraph">
<p>The GUIX string table and string resources are registered with a GUIX
display instance.</p>
</div>
<div class="paragraph">
<p>Each display in a multi-display system has its own string table, and
each display can run in its own selected language. The other GUIX
resource types (colors, fonts, and pixelmaps) are also maintained by the
GUIX Display component, since these resource types are specific to each
display color format and color depth.</p>
</div>
<div class="paragraph">
<p>While you can manually create your application string table, most often
the display string table is defined by the GUIX Studio application as
part of your project resource file. The available languages are also
defined in the resource header file. The display string table is a
multi-column table of pointers to application strings. Each column of
the string table represents one language supported by the application.
If your application supports only one language, for example English,
then your string table will have only one column. Still, you can add
support for additional languages at any time without modifying your
application software.</p>
</div>
<div class="paragraph">
<p>The active string table is assigned by calling the
<strong><em>gx_display_string_table_set</em></strong> API function. This function is called
automatically by the GUIX Studio generated startup code, but can also be
called directly by the application to change the active string table.</p>
</div>
<div class="paragraph">
<p>The active language is assigned by calling the <strong><em>gx_display_active_language_set</em></strong> API function. This function determines which column of the display string table is active.</p>
</div>
<div class="paragraph">
<p>When this function is invoked, a <strong>GX_EVENT_LANGUAGE_CHANGE</strong> event is
sent to all visible GUIX widgets, allowing them to update to display the
newly active string data.</p>
</div>
<div class="paragraph">
<p>Widgets and application software resolve statically defined strings
using string ID values and the <strong><em>gx_display_string_get_ext</em></strong> or
<strong><em>gx_widget_string_get_ext</em></strong> API functions. These functions return
the <strong>GX_STRING</strong> associated with a given string ID and the currently
active language.</p>
</div>
</div>
<div class="sect2">
<h3 id="_bi_directional_text_display">Bi-directional Text Display</h3>
<div class="paragraph">
<p>GUIX provides two strategies for bi-directional text support.</p>
</div>
<div class="paragraph">
<p>One option is to do bidi text reordering within the GUIX Studio
application. Using this option GUIX Studio is responsible for generating
bidi text to the output file in its display order. This solution has
zero impact on the runtime performance and does not require any
additions to the GUIX runtime library. To allow GUIX Studio to generate
display order bidi text strings, you should select the <strong>Generate Bidi
Text in Display Order</strong> checkbox in the GUIX Studio language
configuration dialog:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/configure-languages.png" alt="Configure languages">
</div>
</div>
<div class="paragraph">
<p>With these options selected, the generated resource file will contain
Bidi strings generated in display order, and no extra processing is
required within the GUIX runtime library.</p>
</div>
<div class="paragraph">
<p>The second option is to do bidi text reordering at runtime. This option
is supported for those applications that must handle bidi text string
that are dynamically defined, and not generated by the GUIX Studio
application. In this case, the GUIX runtime library is responsible for
reordering the bidi text before drawing each text string. This solution
has a runtime performance and memory impact. Sufficient dynamic memory
must be available for bidi text reordering process. This solution requires that
the conditional GX_DYNAMIC_BIDI_TEXT_SUPPORT be defined when building the GUIX
library. Two API functions <strong><em>gx_system_bidi_text_enable</em></strong> and
<strong><em>gx_system_bidi_text_disable</em></strong> are provided to enable/disable
bidi text support at runtime.</p>
</div>
<div class="paragraph">
<p>You should not use both <strong>GX_DYNAMIC_BIDI_TEXT_SUPPORT</strong> and configure GUIX Studio to generate Bidi text in display order. You must select one strategy or the other for bidi text string handling.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_memory_usage">Memory Usage</h2>
<div class="sectionbody">
<div class="paragraph">
<p>GUIX resides along with the application program. As a result, the static
memory (or fixed memory) usage of GUIX is determined by the development
tools; e.g., the compiler, linker, and locator. Dynamic memory (or
run-time memory) usage is under direct control of the application.</p>
</div>
<div class="sect2">
<h3 id="_static_memory_usage">Static Memory Usage</h3>
<div class="paragraph">
<p>Most of the development tools divide the application program image into
five basic areas: <em>instruction</em>, <em>constant</em>, <em>initialized data</em>,
<em>uninitialized data</em>, and the <em>GUIX thread stack</em>.  The figure below demonstrates one possible
layout of these memory areas:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./media/guix/user-guide/memory-area-example.png" alt="Memory layout">
</div>
</div>
<div class="paragraph">
<p>It is important to understand that this only an example. The actual
static memory layout is specific to the processor, development tools,
underlying hardware, and the application itself.</p>
</div>
<div class="paragraph">
<p>The instruction area contains all of the program&#8217;s processor
instructions. This area is often located in ROM.</p>
</div>
<div class="paragraph">
<p>The constant area contains various compiled constants, which in GUIX
contains default settings and all application resources (images,
strings, fonts, and colors). In addition, this area contains the
"initial copy" of the initialized data area. During the compiler&#8217;s
initialization process, this portion of the constant area is used to set
up the global initialized data in RAM. The constant area is typically
the largest and usually follows the instruction area and is often
located in ROM.</p>
</div>
<div class="paragraph">
<p>GUIX pixelmaps and fonts typically require large amounts of constant
data storage. These large static data areas are normally kept in ROM or
FLASH.</p>
</div>
<div class="paragraph">
<p>The GUIX thread stack is defined within the uninitialized data area (as
a global variable) in <strong><em>gx_system.h</em></strong> file as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-C" data-lang="C">_gx_system_thread_stack[GX_THREAD_STACK_SIZE];</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>GX_THREAD_STACK_SIZE</strong> is defined in <strong><em>gx_port.h</em></strong>, but may be
overridden by the application by defining this symbol in the
<strong><em>gx_user.h</em></strong> header file or via project options or command line
parameters. The stack size must be large enough to handle the worst case
event handling and nested drawing calls.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dynamic_memory_usage">Dynamic Memory Usage</h3>
<div class="paragraph">
<p>As mentioned before, dynamic memory usage is under direct control of the
application. Control blocks and memory associated with canvases, etc.
can be placed anywhere in the target&#8217;s memory space. This is an
important feature because it facilitates easy utilization of different
types of physical memory&#8201;&#8212;&#8201;at run-time.</p>
</div>
<div class="paragraph">
<p>For example, suppose a target hardware environment has both fast memory
and slow memory. If the application needs extra performance for drawing,
the canvas memory can be explicitly placed in the high-speed memory area
for best performance.</p>
</div>
<div class="paragraph">
<p>Several optional GUIX services and features require a runtime dynamic
memory allocation mechanism, commonly referred to as a heap. These
services and features are completely optional, and many GUIX
applications do not use any heap and do not define a runtime memory
allocation mechanism.</p>
</div>
<div class="paragraph">
<p>If you will be using services which require runtime memory allocation,
you must install functions which GUIX will call when memory must be
dynamically allocated or freed. You can implement these functions as you
prefer, so that even in this case the location of the dynamic memory
pool is under application control. To install support for dynamic memory
allocation, the application should invoke the API service <strong><em>gx_system_memory_allocator_set</em></strong> during program startup to define
your memory allocation and memory free services. Refer to the
documentation of this API for a complete example.</p>
</div>
<div class="paragraph">
<p>GUIX services which require a runtime memory allocation and
de-allocation service include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Loading binary resources from external storage into the GUIX runtime
environment.</p>
</li>
<li>
<p>The software runtime jpeg image decoder.</p>
</li>
<li>
<p>The software runtime png image decoder.</p>
</li>
<li>
<p>Using text widgets with GX_STYLE_TEXT_COPY.</p>
</li>
<li>
<p>Runtime pixelmap resize and rotation utility functions.</p>
</li>
<li>
<p>Runtime screen and widget control block allocation.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For smaller applications, GUIX resources are usually compiled and
statically linked as part of the application image, and binary resource
installation is not required. Binary resources allow an application to
install resources (fonts, images, languages) at runtime loaded from some
storage location, such as a flash drive or a URL.</p>
</div>
<div class="paragraph">
<p>The runtime jpeg and png decoders are optional components. Most GUIX
applications allow the GUIX Studio tool to pre-decode all required image
files, and store them as proprietary GUIX Pixelmap data resources. These
services are provided for completeness for those applications that
require runtime conversion of jpeg and/or PNG images to pixelmap format.</p>
</div>
<div class="paragraph">
<p><strong>GX_STYLE_TEXT_COPY</strong> allows the user to specify that a particular widget or widgets will keep it&#8217;s own private copy of dynamically assigned text. Using this option requires that the memory allocation mechanism be installed prior to use. If this style flag is <strong><span class="underline">not</span></strong> provided when a text type widget is created, the application must allocate static storage areas for all dynamically created and assigned text strings. Automatic variables
should not be used in this case to hold runtime generated string data. If the <strong>GX_STYLE_TEXT_COPY</strong> style is enabled, automatic variables may be used to hold string data assigned to GUIX widgets, since each widget will create its own copy of the assigned text.</p>
</div>
<div class="paragraph">
<p>Pixelmap resize and rotation utility functions return the resulting
translated pixelmap as a new pixelmap available to the application.
Sufficient dynamic memory must be available to hold these runtime
generated pixelmap data blocks if these services are used.</p>
</div>
<div class="paragraph">
<p>Finally, the control blocks for the GUIX screens and widgets can be
statically or dynamically allocated. For smaller applications, it is
common to create all application screens during program startup and use
statically allocated control blocks. For large applications, it is
common to create the screen and child widget controls dynamically on an
as-needed bases. Dynamically allocated control blocks are specified by
selecting the <strong>Runtime Allocate</strong> checkbox in the GUIX Studio properties
view, or by passing in the style flag <strong>GX_STYLE_DYNAMICALLY_ALLOCATED</strong>
when creating a widget via the standard API. Using dynamically allocated
widget control blocks requires that memory allocation and deallocation
services are defined as described above.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_components">GUIX Components</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The GUIX APIs are divided and organized into several basic groups which
correspond to fundamental components of the GUIX system. The fundamental
components
include:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Components</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_SYSTEM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The GUIX system component, responsible for initialization, events, timers, string tables, and visible widget hierarchy management.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_CANVAS</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A drawing area. A Canvas can be a thin abstraction of the hardware frame buffer, or it might also be a pure memory canvas. The canvas type is determined by parameters passed to the gx_canvas_create API function.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_CONTEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The drawing context component. The drawing context contains information about the screen, canvas, and brush, and clipping area for the current drawing operations.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_DISPLAY</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Provides the APIs and driver-level implementations to allow your application and the GUIX widgets to perform drawing on a canvas. GX_DISPLAY is implemented to correctly render graphics on each canvas using that canvas' required color format. The GX_DISPLAY component also manages the resources (colors, fonts, and pixelmaps) available to widgets drawing to canvases linked to each display.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_WIDGET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The basic visible widget object and associated APIs. All GUIX widget types are based on or derived from the basic GX_WIDGET type.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_UTILITY</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Utility functions for working with rectangles, functions for string conversion, and non-ANSI mathematical functions are included in this group.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In addition to these basic components, GUIX includes APIs unique to each
type of widget provided in the library. These APIs are described in Chapter 4 of this User Guide, "Description of GUIX Services".</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_system_component">GUIX System Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The GUIX system component provides several services that are global to
the UI application. These services include: <em>initialization, event
management, display management, resource management, timer management,</em>
and <em>widget management</em>. Each service is essential to the organization
of your application program, and these services are described in more
detail in the following sub-sections.</p>
</div>
<div class="sect2">
<h3 id="_initialization_2">Initialization</h3>
<div class="paragraph">
<p>GUIX initialization is accomplished by the application calling the
service <strong><em>gx_system_initialize</em></strong>, which may be called by the
application from the ThreadX <strong><em>tx_application_define</em></strong> routine
(initialization context) or from application threads. The
<strong><em>gx_system_initialize</em></strong> function initializes all global GUIX data
structures and creates the GUIX system mutex, event queue, timer, and
thread. Once <strong><em>gx_system_initialize</em></strong> returns, the application can
use GUIX.</p>
</div>
</div>
<div class="sect2">
<h3 id="_thread_processing">Thread Processing</h3>
<div class="paragraph">
<p>The internal GUIX thread&#8201;&#8212;&#8201;created during initialization&#8201;&#8212;&#8201;is
responsible for most of the processing in GUIX. The processing in this
thread first completes any additional initialization required by the
underlying display driver. Once this is complete, the GUIX thread enters
a loop which first processes all events present in the GUIX event queue
and then refreshes the screen if required. The screen refresh executes
the necessary GUIX drawing functions, based on what is visible and has
been marked as dirty meaning it needs to be redrawn. When there are no
events and nothing left to refresh on the display, the GUIX thread will
suspend, waiting for the next GUIX event to arrive.</p>
</div>
</div>
<div class="sect2">
<h3 id="_rtos_binding">RTOS Binding</h3>
<div class="paragraph">
<p>The GUIX system component is by default configured to utilize the
ThreadX real time operating system for services such as thread services,
event queue services, and timer services. GUIX can easily be ported to
other operating systems by using the preprocessor directive
GX_DISABLE_THREADX_BINDING and re-building the GUIX library. This
removes the ThreadX dependencies from the GUIX source code, and allows
the application developer to implement the required operating system
services using whatever RTOS is provided by the target system. <a href="appendix-f.html">Appendix
F - GUIX RTOS Binding Services</a> describes the services that need to
be implemented to port GUIX to an operating system other than the
ThreadX operating system.</p>
</div>
</div>
<div class="sect2">
<h3 id="_multithread_safety">Multithread Safety</h3>
<div class="paragraph">
<p>The GUIX API is available from the GUIX thread context as well as other
application threads. Application threads can interact with the GUIX
thread by sending and receiving events, by access to shared variables,
and through use of the GUIX API functions. GUIX uses an internal ThreadX
mutex for multi-thread resource protection. In addition, GUIX prevents
the internal structure of visible widgets from being modified once a
screen refresh operation has begun. APIs which would modify the tree of
visible objects are blocked while drawing operations are in progress,
and released once the screen refresh is complete.</p>
</div>
</div>
<div class="sect2">
<h3 id="_system_timers">System Timers</h3>
<div class="paragraph">
<p>GUIX provides the application with periodic timers, which are often used
for periodic update of data displayed in GUIX windows. This is
accomplished via a ThreadX periodic timer, which is also used to perform
GUIX system-level effects like screen fade in/out, etc.</p>
</div>
<div class="paragraph">
<p>The application can create timers and utilize the same timer facility
that is used internally by GUIX. Of course the application can also
directly create and use ThreadX timers if required. The advantage of the
GUIX timers is that they are very easy to use and are pre-configured to
work within the GUIX event-driven processing system.</p>
</div>
<div class="paragraph">
<p>To create and start a GUIX timer, the application should invoke the
function <strong><em>gx_system_timer_start</em></strong>. The parameters to this function
include a pointer to the calling widget, the timer ID (allowing one
widget to start many timers), and the initial and reschedule timeout
values. If the reschedule timeout value is 0, the timer will only run
one time and will delete itself from the active timer list once it
expires.</p>
</div>
<div class="paragraph">
<p>Once started, the GUIX timer will send GX_EVENT_TIMEOUT events to the
timer owner, either once or periodically depending on the timer
reschedule value. A GUIX timer can be stopped by calling the API
function <strong><em>gx_system_timer_stop</em></strong>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_pen_speed_configuration">Pen Speed Configuration</h3>
<div class="paragraph">
<p>The GUIX system component holds configuration information related to pen speed tracking. GUIX internally generated <strong>GX_EVENT_VERTICAL_FLICK</strong> and
<strong>GX_EVENT_HORIZONTAL_FLICK</strong> events based on the speed and distance of PEN_DOWN events generated by the touch input driver, if any. The application can configure the minimum distance and speed required to trigger these internally generated events using the <strong><em>gx_system_pen_configure</em></strong> API function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_screen_stack">Screen Stack</h3>
<div class="paragraph">
<p>The GUIX system component provides services related to the GUIX screen stack, which is an optional functionality supporting a virtual widget stack onto which screens can be pushed, popped, and retrieved at runtime by the application. The screen stack is useful for managing complex menu systems, wherein the route by which the user may arrive at various states in the menu system is varied. Returning to the previous state in the menu system can be easily done by first pushing the previous screen state, then displaying the new screen, and allowing the new screen to pop the previous state from the screen stack when the current screen is dismissed.</p>
</div>
</div>
<div class="sect2">
<h3 id="_clipboard_maintenance">Clipboard Maintenance</h3>
<div class="paragraph">
<p>GUIX supports a clipboard for copying and pasting text during runtime
execution. This support is provided by the GUIX System component.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dirty_list_maintenance">Dirty List Maintenance</h3>
<div class="paragraph">
<p>GUIX maintains a list of dirty widgets, meaning widgets that are visible
and need to be redrawn due to status changes or being made newly
visible. This dirty list improves drawing performance by allowing GUIX
to do one canvas refresh operation to reflect all current changes to the
UI status, rather than doing a canvas refresh as each UI change is made.
This dirty list is also maintained by the GUIX system component.</p>
</div>
</div>
<div class="sect2">
<h3 id="_animation_control_block_pool">Animation Control Block Pool</h3>
<div class="paragraph">
<p>Applications often desire to execute multiple animation sequences, often
in parallel. GUIX maintains a pool of animation control blocks from
which the application can allocate and use. This frees the application
from statically defining these control blocks and allows them to be
reused at different times, rather than defining a unique animation
control block for every animation that the application might define. The
animation control block pool is also maintained by the GUIX system
component.</p>
</div>
</div>
<div class="sect2">
<h3 id="_system_error_handling">System Error Handling</h3>
<div class="paragraph">
<p>The GUIX system error handler is intended to assist the application in
finding internal system errors in GUIX that might be more difficult to
determine from the API perspective. Whenever a system error occurs
inside of GUIX the internal <strong><em>_gx_system_error_process</em></strong> function
is called. This function saves the error code provided and increments
the total number of system errors detected. The system error variables
are defined as follows:</p>
</div>
<div class="paragraph">
<p>UINT <strong>_gx_system_last_error</strong>;</p>
</div>
<div class="paragraph">
<p>ULONG <strong>_gx_system_error_count</strong>;</p>
</div>
<div class="paragraph">
<p>If the GUIX application is behaving strangely, it is useful to look at
the error count variable in the debugger. If it is set, a good way to
troubleshoot the problem is to set a breakpoint in the
<strong><em>_gx_system_error_process</em></strong> function and see when/where it is
being called from.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_canvas_component">GUIX Canvas Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The canvas component is responsible for all canvas related processing. A
canvas is effectively a virtual frame buffer. Your application must
create at least one canvas in order to produce graphical output.
Typically, you would create at least one canvas for each physical
display supported by your system.</p>
</div>
<div class="paragraph">
<p>All GUIX drawing takes place on a canvas. In simpler or memory
constrained systems, there will likely be only one canvas which might be
directly linked to the visible frame buffer, whereas systems with more
memory and more advanced graphics requirements might require multiple
canvases. Making multiple canvases available for one display enables
features such as screen and window fade-in and fade-out effects.
Canvases can be one of two main types, simple or managed.</p>
</div>
<div class="paragraph">
<p>A simple canvas is an off-screen drawing area used by the application.
GUIX does nothing directly with a simple canvas, but the application can
use a simple canvas to render complex drawing to an off-screen buffer,
and then use this off-screen buffer to refresh the visible canvas when
needed.</p>
</div>
<div class="paragraph">
<p>A managed canvas is automatically displayed within the hardware frame
buffer by GUIX. A managed canvas is included in building a composite
canvas for those systems with enough memory to support multiple managed
canvases. Managed canvases have a Z-order maintained by GUIX, and view
clipping is enforced on all managed canvases.</p>
</div>
<div class="paragraph">
<p>A canvas differs from a frame buffer in that it is more generic. In
memory constrained systems, there may be only one canvas and the memory
for this canvas might be the visible frame buffer memory. However, for
more complex systems supporting more advanced graphical overlays and
multiple canvases, the managed canvases are each allocated their own
memory areas which are distinct from the hardware frame buffer memory.
These managed canvases are rendered into the visible frame buffer during
the frame buffer refresh or toggle operation.</p>
</div>
<div class="paragraph">
<p>For hardware supporting multiple graphics layers, i.e. multiple
overlayed frame buffers, the application can bind one or more canvases
to the hardware graphics layers using the
<strong><em>gx_canvas_hardware_layer_bind</em></strong> API. This service informs the
canvas that it is linked to a particular hardware graphics layer, and
once linked this canvas will attempt to utilize hardware support for
canvas visibility (i.e gx_canvas_show, gx_canvas_hide), canvas alpha
blending (i.e. <strong><em>gx_canvas_alpha_set</em></strong>) and canvas offset within the
display (<strong><em>gx_canvas_offset_set</em></strong>).</p>
</div>
<div class="paragraph">
<p>For architectures other than the simplest single canvas/single frame
buffer organization, the size of a canvas is determined by the
application and may be different than the fixed size of a frame buffer.
It may also be at an offset selected by the application. Other
information, such as Z-order is maintained within the canvas. When the
canvas drawing is complete, the contents of the canvas are transferred
to the physical display by the display driver. In some systems that
don&#8217;t have enough memory for a separate canvas and frame buffer memory
areas, the canvas update is actually made directly to the physical
display via the display driver.</p>
</div>
<div class="sect2">
<h3 id="_canvas_creation">Canvas Creation</h3>
<div class="paragraph">
<p>A canvas object can be created during initialization or anytime during
the execution of application threads. There is no limit on the number of
canvas objects that can be created by an application. Most applications,
however, will create only one canvas object for all GUIX drawing.</p>
</div>
</div>
<div class="sect2">
<h3 id="_canvas_control_block">Canvas Control Block</h3>
<div class="paragraph">
<p>The characteristics of each canvas object are found in its control block
<strong>GX_CANVAS</strong> and is defined in <strong><em>gx_api.h</em></strong>. The memory required
for a canvas object is provided by the application and can be located
anywhere in memory. However, it is most common to make the canvas object
control block and the drawing area a global structure by defining them
outside the scope of any function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_canvas_alpha_channel">Canvas Alpha Channel</h3>
<div class="paragraph">
<p>GUIX supports alpha-blending of foreground and background colors on many
levels, including bitmap alpha channel which specifies a blending ratio
per pixel, brush alpha which specifies the blending ratio for a brush at
16 bpp and higher color depths, and canvas alpha which specifies the
blending ratio for an overlay canvas.</p>
</div>
<div class="paragraph">
<p>The alpha value of a canvas is used when there are multiple canvases
which are composited together for display within the frame buffer. If
the canvas Z-order is such that a canvas is above other canvases, then
the canvas alpha value can be set to blend the canvas with those that
lie behind. Rapidly modifying the alpha value of a canvas is used to
provide "fade in" screen transition effects, but the canvas alpha can be
used in many ways.</p>
</div>
<div class="paragraph">
<p>If a canvas is bound to a hardware graphics layer using
gx_canvas_hardware_layer_bind(), GUIX will attempt to implement
canvas alpha blending utilizing hardware support, minimizing the
software overhead associated with blending an overlay canvas.</p>
</div>
<div class="paragraph">
<p>Alpha values range from 0 through 255, where a value of 0 means the
pixel is fully transparent and values greater than 0 are increasing less
transparent canvas alpha value can only be supported for screen drivers
running at 16-bpp and higher unless hardware assistance for canvas
blending is provided.</p>
</div>
</div>
<div class="sect2">
<h3 id="_canvas_offset">Canvas Offset</h3>
<div class="paragraph">
<p>A canvas can be offset within the visible frame buffer by invoking the
<strong><em>gx_canvas_offset_set</em></strong> API service. Canvas offsets are usually used
to implement sprite animations. If a canvas is bound to a hardware
graphics layer by invoking the <strong><em>gx_canvas_hardware_layer_bind</em></strong> API function,
GUIX will attempt to implement canvas offset changes utilizing hardware
support, minimizing the software overhead associated with shifting the
canvas position.</p>
</div>
</div>
<div class="sect2">
<h3 id="_canvas_drawing">Canvas Drawing</h3>
<div class="paragraph">
<p>The GUIX canvas component provides a full drawing API to the
application. Before the drawing APIs such as <strong><em>gx_canvas_line_draw</em></strong> or
<strong><em>gx_canvas_pixelmap_draw</em></strong> can be invoked, the target canvas must be
opened for drawing by invoking the <strong><em>gx_canvas_drawing_initiate</em></strong> API
function. This function prepares a canvas for drawing and creates a
<strong><em>drawing context</em></strong>.</p>
</div>
<div class="paragraph">
<p>The drawing APIs that render to the canvas, such as <strong><em>gx_canvas_line_draw</em></strong> or <strong><em>gx_canvas_text_draw</em></strong>, use parameters found in the current drawing context brush to define the line style, width, and colors. These brush parameters are modified by calling the <strong><em>gx_context_brush_define</em></strong>, <strong><em>gx_context_brush_set</em></strong>,
<strong><em>gx_context_brush_style_set</em></strong>, and similar API functions after a drawing context has been established by calling <strong><em>gx_canvas_drawing_initiate</em></strong>.</p>
</div>
<div class="paragraph">
<p>When GUIX invokes the window and widget drawing functions as part of a deferred canvas refresh operation, the target canvas is opened for drawing prior to calling the widget drawing function(s). Therefore the standard widget drawing functions are not required to open the target canvas, this has been done for them.</p>
</div>
<div class="paragraph">
<p>In some cases the application may want to force immediate drawing to a canvas. In this case, the application can perform the following steps.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Call the <strong><em>gx_canvas_drawing_initiate</em></strong> API function, passing in the target canvas and rectangle within that canvas on which the application wants to draw.</p>
</li>
<li>
<p>Call any number of canvas drawing APIs to accomplish the desired drawing.</p>
</li>
<li>
<p>Call the <strong><em>gx_canvas_drawing_complete</em></strong> API function to signal that drawing has been completed. This flushes the canvas to the visible frame buffer and/or triggers a buffer toggle operation, depending on the system memory architecture.</p>
</li>
</ol>
</div>
</div>
<div class="sect2">
<h3 id="_drawing_apis">Drawing APIs</h3>
<div class="paragraph">
<p>There are several principal drawing primitives that are required by GUIX to draw all the visual elements on the screen. These drawing APIs can
also be invoked by application software, usually as part of a custom widget drawing function. These GUIX canvas drawing APIs perform
parameter validation and clipping, and then pass the clipped drawing coordinates down to the display driver for hardware and color-format
specific drawing implementations. These drawing API functions are defined as follows.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>gx_canvas_alpha_set</p>
</li>
<li>
<p>gx_canvas_arc_draw</p>
</li>
<li>
<p>gx_canvas_block_move</p>
</li>
<li>
<p>gx_canvas_circle_draw</p>
</li>
<li>
<p>gx_canvas_ellipse_draw</p>
</li>
<li>
<p>gx_canvas_glyphs_draw</p>
</li>
<li>
<p>gx_canvas_hardware_layer_bind</p>
</li>
<li>
<p>gx_canvas_hide</p>
</li>
<li>
<p>gx_canvas_line_draw</p>
</li>
<li>
<p>gx_canvas_offset_set</p>
</li>
<li>
<p>gx_canvas_pie_draw</p>
</li>
<li>
<p>gx_canvas_pixel_draw</p>
</li>
<li>
<p>gx_canvas_pixelmap_blend</p>
</li>
<li>
<p>gx_canvas_pixelmap_rotate</p>
</li>
<li>
<p>gx_canvas_pixelmap_tile</p>
</li>
<li>
<p>gx_canvas_polygon_draw</p>
</li>
<li>
<p>gx_canvas_rectangle_draw</p>
</li>
<li>
<p>gx_canvas_rotated_text_draw</p>
</li>
<li>
<p>gx_canvas_shift</p>
</li>
<li>
<p>gx_canvas_show</p>
</li>
<li>
<p>gx_canvas_text_draw</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The drawing API is invoked via the GUIX Canvas API, and all drawing is done using gx_canvas_* API functions. Drawing is done using the current brush in the current drawing context. Any of the shape drawing functions above can be outlined, solid color filled, or pixelmap filled as defined by the current brush. To modify the shape outline width, color, or fill, use the gx_context_brush_* API functions to define the brush within the current drawing context.</p>
</div>
<div class="paragraph">
<p>The above application level drawing APIs don&#8217;t do actual drawing to the
canvas, but instead verify the caller&#8217;s parameters before invoking the
display driver level drawing function. The driver level drawing function
actually writes pixel data into the canvas memory.</p>
</div>
<div class="paragraph">
<p>GUIX provides stock or generic display driver drawing functions for
various color depths, including 1, 2, 4, 8, 16, 24, and 32 bits per
pixel (bpp). In some cases, the default software drawing implementation
is replaced by hardware-accelerated implementations for those hardware
targets that provide a 2D drawing accelerator.</p>
</div>
</div>
<div class="sect2">
<h3 id="_color_depth">Color Depth</h3>
<div class="paragraph">
<p>GUIX supports color depths up to 32-bpp as well as monochrome and
grayscale. The type of color depth support largely determined by the
capabilities of the underlying physical display and also has an impact
on how much memory is required for the canvas drawing area. The
following is a list of color depth support along with a brief
description of the variations within that color depth.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Color&nbsp;Format</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1-bit monochrome</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1-bit per pixel packed format.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2-bit grayscale</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4 gray levels, packed four pixels per byte.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4-bit grayscale</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">16 gray levels, packed two pixels per byte.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4-bit color</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A VGA format planar memory organization.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">8-bit grayscale</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">256 gray levels</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">8-bit palette mode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1 byte per pixel used as palette index</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">8-bit r:g:b mode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A less commonly used 2:3:2 r:g:b format.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">16-bit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each pixel requires two bytes. Can be r:g:b or b:g:r byte order. Normally 5:6:5 structure, but can also be 5:5:5 structure or 4:4:4:4 a:r:g:b structure.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">24-bit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each pixel requires 3 (packed format) or 4 (unpacked format) bytes. Can be in r:g:b or b:g:r byte order as required by hardware.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">32-bit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each pixel requires 4 bytes with an alpha channel. Can be a:r:g:b or b:g:r:a byte order and determined by hardware.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_mouse_support">Mouse Support</h3>
<div class="paragraph">
<p>GUIX supports drawing a mouse cursor on any desired canvas. The mouse
cursor can be drawing in software or might be supported by hardware
cursor overlay. In either case, the API provided to the application
related to mouse cursor support is the same whether using software or
hardware mouse cursor drawing.</p>
</div>
<div class="paragraph">
<p>GUIX mouse support is only enabled if the <code>#define GX_MOUSE_SUPPORT</code> is defined in the gx_user.h header file before building the GUIX library.</p>
</div>
<div class="paragraph">
<p>The application must define the mouse cursor and hotspot using the
<strong><em>gx_canvas_mouse_define</em></strong> API function. This API accepts a pointer to the canvas
on which the cursor image should be drawn, and a pointer to a
<strong>GX_MOUSE_CURSOR_INFO</strong> structure, which defines the mouse cursor image
and hotspot of the mouse image relative the image top-left corner.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_display_component">GUIX Display Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The display component is fundamental in GUIX, since it manages the
processing of all display objects, which in themselves contain one or
more canvases, widgets, and windows. The display component also
interacts with the underlying hardware screen driver associated with
each display through a series of function pointers.</p>
</div>
<div class="sect2">
<h3 id="_display_creation">Display Creation</h3>
<div class="paragraph">
<p>A display object can be created during initialization or anytime during
the execution of application threads. Typically an application creates
one display object to manage each physical screen. If you have used GUIX
Studio to define your application and the physical displays available,
you will use the gx_studio_display_configure API function to create
and initialize each of your displays.</p>
</div>
</div>
<div class="sect2">
<h3 id="_display_control_block">Display Control Block</h3>
<div class="paragraph">
<p>The characteristics of each display object are found in its control
block <strong><em>GX_DISPLAY</em></strong> and are defined in <strong><em>gx_api.h</em></strong>. The memory
required for a display object is provided by the application and can be
located anywhere in memory. However, it is most common to make the
display control block a global structure by defining it outside the
scope of any function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_resource_management">Resource Management</h3>
<div class="paragraph">
<p>Resources are UI components that are needed by the application, but they
are not application code. Resources are application data and are usually
statically defined. Resource types include pixelmaps, fonts, colors, and
strings. These resources can be changed at any time, usually without
changing any application software. It is important to keep the storage
of and references to resources separated from the application software
to allow changing UI appearance without changing application code since
changes to the application software usually require the associated
re-testing and verification of that software.</p>
</div>
<div class="paragraph">
<p>The GUIX <strong><em>display</em></strong> module provides resource management facilities
for all resources that are dependent on the color depth and format of
the display. These facilities include maintaining the active pixelmap
table, active font table, and active color table. The string table
resource is maintained by the GUIX system module, since string resources
do not normally need to be changed based on color depth and format.</p>
</div>
<div class="paragraph">
<p>The application software references resources by their resource ID,
which is an index into the corresponding resource table. This allows the
table to be changed, for example the color table might be changed when a
product changes from "day mode" to "night mode", but the color ID values
to remain the same.</p>
</div>
<div class="paragraph">
<p>Your application resources are written to a resource file (or set of
resource files) by the GUIX Studio application. Default colors,
pixelmaps, and fonts are provided automatically when you create a new
GUIX Studio project, but these defaults are easily replaced as you
define the look and feel of your application.</p>
</div>
<div class="paragraph">
<p>It is important to note that Resource IDs for colors, fonts, and
pixelmaps cannot be resolved to their actual color, font, or pixelmap
values until the active Display component is known. Since the GUIX
architecture supports multiple active displays, Resource IDs can only be
resolved to resource values when a widget and its associated Resource ID
can be resolved to a specific display. This property is known as dynamic
binding. The Resource ID for a property such as a text color, for
example the resource ID <strong>GX_COLOR_ID_TEXT,</strong> might resolve to a
16-bit R:G:B value for white when used on one display, but the same
color ID might resolve to a monochrome black color value when used on
another display.</p>
</div>
<div class="paragraph">
<p>In practice this dynamic binding of Resources IDs to resource values
means that application software and GUIX internal components should most
often only resolve Resource IDs to resource values within an active
drawing context. An active drawing context specifies the currently
active display, which allows GUIX to resolve each Resource ID to a
specific resource value. If the application software is required to find
a specific resource value outside of a drawing context, this can also be
done for visible widgets. Visible widgets are linked to a root window
which can also be used to resolve the active canvas and display for that
widget.</p>
</div>
<div class="paragraph">
<p>If a widget has been created but not yet displayed (i.e., has not been
linked to any root window or other visible parent), any resource IDs
associated with that widget cannot be resolved to a specific resource
value other than by directly indexing into the resource table assigned
to a specific display. This direct access to a specific resource table
can safely be done by the application software, but is never done in the
internal GUIX library software.</p>
</div>
</div>
<div class="sect2">
<h3 id="_widget_defaults">Widget Defaults</h3>
<div class="paragraph">
<p>The GUIX display component also provides default definitions for various
widget attributes. Unless otherwise specified by the application,
widgets/windows are created with these system attributes. These system
attributes are mainly composed of fonts, colors, and bitmaps maintained
in the system resource tables. Additional attributes for default
scrollbar appearance are also maintained by the GUIX display component.</p>
</div>
<div class="paragraph">
<p>The default color settings are defined by the color table assigned to
each display and the pre-defined default color IDs. These default color
IDs include the following.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Color ID</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_CANVAS</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default canvas (i.e. display background) color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_WIDGET_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default widget fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_WINDOW_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default window fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_DISABLED_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default disabled widget fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_DEFAULT_BORDER</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default widget border color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_WINDOW_BORDER</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default window border color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SELECTED_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default selected text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_DISABLED_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default disabled text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SELECTED_TEXT_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default selected text fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_READONLY_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default readonly text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_READONLY_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default readonly text fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SCROLL_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scrollbar fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SCROLL_BUTTON</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scrollbar button fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SHADOW</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default shadow color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SHINE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default highlight color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_BUTTON_BORDER</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Button widget border color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_BUTTON_UPPER</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Button widget upper fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_BUTTON_LOWER</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Button widget lower fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_BUTTON_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Button widget text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_TEXT_INPUT_TEXT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Text input widget text color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_TEXT_INPUT_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Text input fill color</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_TICK</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to draw slider tick marks.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_GROOVE_BOTTOM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to draw slider groove</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_NEEDLE_OUTLINE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to draw needle outline</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_NEEDLE_FILL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to fill slider needle</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_NEEDLE_LINE1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to draw needle highlight</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_COLOR_ID_SLIDER_NEEDLE_LINE2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Color used to draw needle shadow</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>These color ID values are mapped to a specific color value as defined by
the color table assigned to each display. These defaults can be changed
as a group for one display by calling the
<strong><em>gx_display_color_table_set</em></strong> API function. If you are
using GUIX Studio, the display color table is automatically initialized
when your application calls the <strong><em>gx_studio_display_configure</em></strong>
function.</p>
</div>
<div class="paragraph">
<p>The GUIX display component also maintains a default font table. The
default font table defines the font used by each widget type unless
specifically specified by the application. The pre-defined display font
table IDs include the following values.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Font&nbsp;ID</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_FONT_ID_DEFAULT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default font used when no specific font is defined</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_FONT_ID_BUTTON</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default font used for all text on buttons</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_FONT_ID_TEXT_INPUT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default font used for text edit fields</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The font ID used by any text type widget can be re-assigned by using the
<strong>gx_<widget_type>_font_set</strong> API provided for each text-related widget type. The entire font table can be re-assigned by calling the <strong>gx_display_font_table_set</strong> API function.</widget_type></p>
</div>
</div>
<div class="sect2">
<h3 id="_scrollbar_appearance">Scrollbar Appearance</h3>
<div class="paragraph">
<p>GUIX Display also maintains default scrollbar appearance settings for
that display. These settings are defined by the <strong>GX_SCROLLBAR_APPEARANCE</strong> structure
which is defined below. GUIX Display maintains one scrollbar appearance
structure for vertical scrollbars and a second structure for horizontal
scroll bars. The application can modify the default scrollbar appearance
for any display by initializing a <strong>GX_SCROLLBAR_APPEARANCE</strong> structure and invoking the API function
<strong><em>gx_display_scroll_appearance_set</em></strong>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">typedef struct GX_SCROLLBAR_APPEARANCE_STRUCT
{
    GX_VALUE       gx_scroll_width;
    GX_VALUE       gx_scroll_thumb_width;
    GX_VALUE       gx_scroll_thumb_travel_min;
    GX_VALUE       gx_scroll_thumb_travel_max;
    GX_UBYTE       gx_scroll_thumb_border_style;
    GX_RESOURCE_ID gx_scroll_fill_pixelmap;
    GX_RESOURCE_ID gx_scroll_thumb_pixelmap;
    GX_RESOURCE_ID gx_scroll_up_pixelmap;
    GX_RESOURCE_ID gx_scroll_down_pixelmap;
    GX_RESOURCE_ID gx_scroll_thumb_color;
    GX_RESOURCE_ID gx_scroll_thumb_border_color;
    GX_RESOURCE_ID gx_scroll_button_color;
} GX_SCROLLBAR_APPEARANCE;</code></pre>
</div>
</div>
<div class="paragraph">
<p>| GX_SCROLLBAR_APPEARANCE Structure Member | Description |
|&#8201;&#8212;&#8201;|&#8201;&#8212;&#8201;|
| gx_scroll_width | Width of a vertical scrollbar or height of a horizontal scrollbar, in pixels. |
| gx_scroll_thumb_width | Width of the elevator and end buttons, in pixels. |
| gx_scroll_thumb_travel_max | Offset from the end of scroll bar to maximum thumb button travel point. |
| gx_scroll_fill_pixelmap | Pixelmap used to fill scroll background. |
| gx_scroll_thumb_pixelmap | Pixelmap used to draw scroll thumb button. |
| gx_scroll_up_pixelmap | Pixelmap used to draw scroll up button. |
| gx_scroll_down_pixelmap | Pixelmap used to draw scroll down button. |
| gx_scroll_fill_color | Color ID of color used to fill scrollbar background. |
| gx_scroll_button_color | Color ID of color used to fill scrollbar thumb button. |</p>
</div>
<div class="paragraph">
<p>In addition to these default settings for fonts, color, and styles, the
application may specify any of the parameters on a case by case basis as
desired using API provided by each widget type.</p>
</div>
</div>
<div class="sect2">
<h3 id="_skinning_and_themes">Skinning and Themes</h3>
<div class="paragraph">
<p>Skinning allows GUIX widgets and windows to easily change their base
appearance, i.e., changing the "skin" in one place will change the base appearance
of all associated widgets and windows.</p>
</div>
<div class="paragraph">
<p>Re-skinning your GUIX application requires that you supply a new color,
font and or pixelmap table to the GUIX Display resource tables. Since
all GUIX widgets refer to their color, bitmap, or font by resource ID,
providing a new resource table automatically causes all GUIX widgets to
begin using your new colors and pixelmaps when they draw themselves to
the desired display.</p>
</div>
<div class="paragraph">
<p>A new set of fonts, colors, and pixelmaps that are designed to work
together to provide an attractive appearance is called a <em>theme</em>. A
theme defines a set of resource tables and the size of each resource
table. Any number of themes can be defined for any display using the
GUIX Studio application. You must pass the starting theme index to the
GUIX Studio generated function <strong><em>gx_studio_display_configure</em></strong>, which
installs the initial theme into the created display. The active theme
for any display can be changed at any time by calling the function
<strong><em>gx_display_theme_install</em></strong>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_root_window">Root Window</h3>
<div class="paragraph">
<p>For each visible canvas created by an application, the application must
also create one Root Window for that canvas. This special window
basically acts as a container for all the top-level application windows
and widgets. The root window draws the canvas background, and since the
root window is derived from the <strong>GX_WINDOW</strong> class the root window can
also have wallpaper. To change the background color of your display or
canvas, you simply change the fill color of the root window attached to
that canvas.</p>
</div>
<div class="paragraph">
<p>If you use the GUIX Studio generated function named
<strong><em>gx_studio_display_configure</em></strong> to configure your displays, then the
canvas and root window for each display are created for you as part of
this initialization function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_anti_aliasing">Anti-Aliasing</h3>
<div class="paragraph">
<p>Anti-Aliasing is an optional feature in GUIX that is used to smooth
lines, curves, and fonts. Anti-aliasing is only supported when running
with a display driver utilizing 16-bpp or higher color depth.</p>
</div>
<div class="paragraph">
<p>Anti-aliased line drawing is enabled by setting the <strong>GX_BRUSH_ALIAS</strong>
flash in the active brush. This applies to lines drawn directly as well
as to lines drawn as the border of a polygon or circle.</p>
</div>
<div class="paragraph">
<p>Anti-aliased text drawing is enabled by using an anti-aliased font which
is produced by the GUIX studio application. You specify whether a font
should be generated as antialiased or binary when you create the font.
Anti-aliased fonts in GUIX utilize 16 levels of transparency for each
pixel.</p>
</div>
</div>
<div class="sect2">
<h3 id="_clipping">Clipping</h3>
<div class="paragraph">
<p>Clipping is supported internally by the GUIX display component, and at
the window and widget layers by the parent-child architecture maintained
by GUIX widgets. No window or widget is ever allowed to draw outside of
that widget&#8217;s area, and a widget is never allowed to draw outside of the
area of that widget&#8217;s parent.</p>
</div>
<div class="paragraph">
<p>This also prevents widgets from drawing at pixel coordinates that lay
outside of the canvas memory which likely lead to memory corruption or a
system failure. Widgets are not allowed to draw outside of the widget&#8217;s
area, the widget&#8217;s parent area, or beyond the canvas extent.</p>
</div>
<div class="paragraph">
<p>In addition, widgets can only draw to areas that have previously been
marked as dirty. This prevents an entire window being drawn, for
example, when only a corner of the window has been revealed. Only the
portion of the window that actually needs to be refreshed is marked as
dirty, and so the window drawing function only truly refreshes pixels in
the dirty area.</p>
</div>
<div class="paragraph">
<p>The GUIX display component enforces these clipping algorithms before
invoking the driver level drawing functions.</p>
</div>
</div>
<div class="sect2">
<h3 id="_views">Views</h3>
<div class="paragraph">
<p>GUIX always maintains a set of views for each root window and each child
window of the root window. Views are a dynamic, run-time determined
clipping area that changes as window position and Z-order are modified.
GUIX uses views to prevent a window or widget in the background from
drawing on top of a window or widget in the foreground. Views enforce
Z-order discipline. In addition, views are important for efficiency in
that they prevent a window in the background from drawing to any area of
the canvas that cannot be seen. If a window is completely covered by
another window, the covered window will not be allowed to draw to the
canvas at all, even if it is attempting to do so.</p>
</div>
</div>
<div class="sect2">
<h3 id="_display_driver_interface">Display Driver Interface</h3>
<div class="paragraph">
<p>GUIX display drivers are responsible for all interaction with the
underlying physical screen. The display drivers have three basic
functions: initialization, drawing, and frame buffer display.
Initialization is responsible for preparing the physical display
hardware, informing GUIX of the properties of the physical display
hardware, and for informing GUIX which specific drawing functions should
be used. The main display driver initialization is called from the GUIX
<strong><em>gx_display_create</em></strong> function. In addition, the GUIX thread will
also call a secondary display driver initialization from the thread
context. This secondary display driver is only needed if the driver
requires RTOS services during its initialization, e.g., device
interrupts or <strong><em>tx_thread_sleep</em></strong> requests for delay between steps
in the initialization process.</p>
</div>
<div class="paragraph">
<p>Once initialization is complete, the display driver is responsible for
any direct drawing that can be done in the physical display hardware.
Finally, the display driver is responsible for displaying the frame
buffer.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_widget_component">GUIX Widget Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A GUIX widget is a visible graphical element. There are GUIX components
which are not visible, such as timers and math utility functions.
However all visible components are derived from the basic GUIX widget
component. A GUIX widget is the primary building block of the GUIX
display&#8201;&#8212;&#8201;all other graphic elements are derived from the base widget
functionality.</p>
</div>
<div class="paragraph">
<p>GUIX widgets are implemented in an object oriented manner with full
support of inheritance. This is accomplished using ANSI C, which results
in the smallest possible memory and processing requirements. When we
speak of one particular widget, such as <strong>GX_BUTTON</strong>, being <em>derived
from</em> another widget, such as the base <strong>GX_WIDGET</strong>, what we mean is
that the <strong>GX_BUTTON</strong> control structure contains all of the member
variables and function pointers of <strong>GX_WIDGET</strong>, with some additional
variables that are specific to <strong>GX_BUTTON</strong>. GUIX builds up layers of
widgets in this fashion, so that more complex widgets are always based
on a simpler widget before them. This hierarchical model of derivation
makes it easier to learn the APIs used to modify widget parameters. If
you want to modify the color of a button, you use the same API you use
to modify the color of a widget, namely
<strong><em>gx_widget_fill_color_set</em></strong>.</p>
</div>
<div class="paragraph">
<p>The organization of visible widgets is maintained in a parent-child
manner using tree structured lists linking child widgets to their
parents. The children inherit characteristics from their parents such as
the views into which they can draw and the canvas on which they draw.
Child widgets may have their own child widgets, again inheriting various
characteristics from the parent. The characteristics of any widget may
be explicitly redefined via various GUIX API calls.</p>
</div>
<div class="sect2">
<h3 id="_widget_creation">Widget Creation</h3>
<div class="paragraph">
<p>A widget object can be created during initialization or anytime during
the execution of application threads. There is no limit on the number of
widget objects that can be created by an application. There is also no
limit on the number of children any widget may have, within the memory
limits of your target hardware.</p>
</div>
<div class="paragraph">
<p>Each widget type has its own create function, such as
<strong><em>gx_button_create</em></strong> or <strong><em>gx_prompt_create</em></strong>. The first three
parameters to these functions are always the same, namely a pointer to
the widget control structure, a string pointer to the widget name, and a
pointer to the widget&#8217;s parent. Each create function may have any number
of additional parameters depending on the requirements of that
particular widget type.</p>
</div>
</div>
<div class="sect2">
<h3 id="_widget_control_block">Widget Control Block</h3>
<div class="paragraph">
<p>The characteristics of each widget object are found in its control block
<strong>GX_WIDGET</strong> and are defined in <strong><em>gx_api.h</em></strong>. The memory required
for a widget object is provided by the application and can be located
anywhere in memory. However, it is most common to make the widget object
control block a global structure by defining it outside the scope of any
function. If you are using GUIX Studio, your widget control blocks can
be statically allocated within your Studio generated specifications
file, or they can be dynamically allocated by your application.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dynamic_widget_control_block_allocation_and_de_allocation">Dynamic Widget Control Block Allocation and De-allocation</h3>
<div class="paragraph">
<p>If you are using dynamic control block allocation, you will need to
define two functions that GUIX will use to allocate and free the memory
required for your widget control blocks. Your functions for memory
management are passed to the GUIX system component via the
<strong><em>gx_system_memory_allocator_set</em></strong> API function. This function allows
you to pass two function pointers into GUIX: the first is a pointer to a
memory allocation function, and the second is a pointer to a memory free
function. Most often, you will implement these functions using ThreadX
byte pools, but the design of GUIX allows you to implement dynamic
memory management in whatever way you prefer.</p>
</div>
<div class="paragraph">
<p>Dynamic widget allocation is most often employed within your Studio generated application specifications file, when you select the "dynamically allocated" option in the Studio widget properties field. However, you can also use dynamic control block allocation within your application. If you use dynamic control block allocation within your application, you should invoke the <strong><em>gx_widget_allocate</em></strong> API function to allocate the widget control block. Next, when you create the widget, make certain you pass the <strong>GX_WIDGET_STYLE_DYNAMICALLY_ALLOCATED</strong> style flag (along with any other needed style flags) to the widget create function. This flag is used to mark the widget as being dynamically allocated in the widget status field. When and if the widget is later deleted using <strong><em>gx_widget_delete</em></strong>, GUIX will check this status field and automatically call your memory de-allocator function to ensure there are no memory leaks.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
A widget created using a dynamically allocated control block must be created with the <strong>GX_WIDGET_STYLE_DYNAMICALLY_ALLOCATED</strong> style flag to prevent memory loss.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_types">Types</h3>
<div class="paragraph">
<p>GUIX provides a rich, fully functional set of built-in widgets. As
mentioned previously, all specialized widgets are derived from the base
widget. Following is a list of the built-in widgets in GUIX:</p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_WIDGET</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_TEXT_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_MULTI_LINE_TEXT_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_RADIO_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_CHECKBOX</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_PIXELMAP_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_ICON_BUTTON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_ICON</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_SPRITE</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_SLIDER</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_PIXELMAP_SLIDER</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_VERTICAL_SCROLL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_HORIZONTAL_SCROLL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_PROGRESS_BAR</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_PROMPT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_NUMERIC_PROMPT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_PIXELMAP_PROMPT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_NUMERIC_PIXELMAP_PROMPT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_SINGLE_LINE_TEXT_INPUT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_MULTI_LINE_TEXT_VIEW</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_MULTI_LINE_TEXT_INPUT</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_WINDOW</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_ROOT_WINDOW</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_VERTICAL_LIST</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_HORIZONTAL_LIST</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_POPUP_LIST</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_DROP_LIST</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_LINE_CHART</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_DIALOG</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_KEYBOARD</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_SCROLL_WHEEL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_TEXT_SCROLL_WHEEL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_STRING_SCROLL_WHEEL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_NUMERIC_SCROLL_WHEEL</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_CIRCULAR_GAUGE</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_RADIAL_PROGRESS_BAR</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_RADIAL_SLIDER</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_MENU_LIST</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_MENU</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_ACCORDION_MENU</strong></p>
</div>
<div class="paragraph">
<p><strong>GX_TYPE_TREE_VIEW</strong></p>
</div>
</div>
<div class="sect2">
<h3 id="_styles">Styles</h3>
<div class="paragraph">
<p>Widget styles consist of things like border properties (raised,
recessed, thin, thick, or no boarder at all) as well as properties for
specific widget types, as listed previously. The widget style flags
offer the simplest method for modifying the appearance of any widget.
The initial widget style is always a parameter passed to the widget type
specific create function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_colors">Colors</h3>
<div class="paragraph">
<p>Widgets draw themselves using colors defined in the system color table.
Color IDs are defined for canvas background, default widget fill color,
button fill color, text widget fill color, window fill color, and
several other default color values. In addition,
<strong>GX_WINDOW</strong> objects support displaying a bitmap or wallpaper as the
window client is filled.</p>
</div>
<div class="paragraph">
<p>The simplest method of changing the default color scheme is to use GUIX
Studio and create or define a color scheme that meets your requirements.
You can also define your color scheme manually by creating an array of
GX_COLOR values and invoking the gx_system_color_table_set API
function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_event_notification">Event Notification</h3>
<div class="paragraph">
<p>GUIX events are requests made to one or more widgets to perform a
particular action and notifications to notify widgets of user input and
internal system status changes. For example, when a widget gains focus,
the <strong>GX_EVENT_FOCUS_GAINED</strong> is sent to the widget via the
<strong><em>gx_system_event_send</em></strong> API service.</p>
</div>
<div class="paragraph">
<p>Events are passed through the GUIX event queue, and each event is an
instance of the <strong>GX_EVENT</strong> data structure. The <strong>GX_EVENT</strong> data
structure is defined in <strong><em>gx_api.h</em></strong>, however the most important
fields of the structure are the <strong>gx_event_type</strong>,
<strong>gx_event_sender</strong>, <strong>gx_event_target</strong>, and
<strong>gx_event_payload</strong>.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_event_type</strong> field is used to identify the particular event
class. The event type indicates if this is, for example, a
<strong>GX_EVENT_PEN_DOWN</strong> event or a
<strong>GX_EVENT_TIMER</strong> event. The <strong>gx_event_payload</strong> is a union of
various data fields, and they are not all valid for every event type.
You use the event type field first, before examining the other event
data fields.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_event_sender</strong> field contains the ID of the widget that
generated the event if the event is a child-widget notification.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_event_target</strong> field can be used to route user-defined
events to a particular window or widget. If you want to send an event to
a particular window, you should give the window a unique ID value (so
that it can be positively identified), and when building the event place
the window ID value in the <strong>gx_event_target</strong> field. If you don&#8217;t
know the target ID or if you just want the event to be routed to the
widget that has input focus, make sure to set the
<strong>gx_event_target</strong> field to 0.</p>
</div>
<div class="paragraph">
<p>Finally, the <strong>gx_event_payload</strong> field is a union of various data
types. For <strong>GX_EVENT_PEN_DOWN</strong> and <strong>GX_EVENT_PEN_UP</strong> events, the
<strong>gx_event_pointdata</strong> field contains the x,y pixel coordinate the
pen position. For timer events, the <strong>gx_event_timer_id</strong> field contains
the ID of the expired timer. Other payload data fields are utilized for
other event types. The complete list of pre-defined event types and
their payload fields is defined in <a href="appendix-e.html">Appendix E - GUIX Event Descriptions</a>.</p>
</div>
<div class="paragraph">
<p>The application can also add its own custom events, starting numerically
after the constant <strong>GX_FIRST_APP_EVENT</strong>. All event numbers after
this constant are reserved for the application&#8217;s use. Of course, the
application&#8217;s widget event handler must have processing for such
application events.</p>
</div>
</div>
<div class="sect2">
<h3 id="_event_processing_2">Event Processing</h3>
<div class="paragraph">
<p>There is a default widget event processing function for each and every
widget, named <strong><em>gx</em>&lt;widget-type&gt;_event_process_</strong>. In most cases,
the application won&#8217;t need to worry about the event handling of any
given widget. However, in situations where the application requires
custom or supplemental event processing, the application may override
the default processing function with its own via the GUIX API
<strong><em>gx_widget_event_process_set</em></strong>. This function overrides the
default event processing function with the event function processing
function specified in the API.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Application event processing
functions can take advantage (i.e., not duplicate the processing) of
the default processing by simply calling the default
<strong><em>gx_widget_event_process</em></strong> processing directly.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Event processing is called exclusively from the context of the internal
GUIX system thread. In this way, the stack requirements to process the
event handling only applies to the GUIX thread.</p>
</div>
</div>
<div class="sect2">
<h3 id="_implementing_custom_event_processing_example">Implementing Custom Event Processing (example)</h3>
<div class="paragraph">
<p>You can provide your own event processing function for any widget or
window in the GUIX system. If you are creating your own custom widget
type, you will normally install your custom event handler in the widget
creation function. If you are just extending or modifying the operation
of an existing widget or window, you can call the
gx_widget_event_process_set API function after the widget or window
has been created. You will almost always provide your own event handling
for your top-level windows (also called Screens) in order to process
events generated by your child controls. Processing event generated by
the child controls of a screen is the main way you add functionality to
your GUIX application.</p>
</div>
<div class="paragraph">
<p>As an example, suppose you define a top-level screen named "main_menu".
This screen might be defined using GUIX Studio, or you might create this
screen in your application code. If you define the screen within GUIX
Studio, you simply type the name of your event handler in the Studio
properties field for that screen, and the Studio generated
specifications code will automatically install your event handler. In
this case, we will call the custom event handler
<strong><em>main_menu_event_handler</em></strong> and it should be coded like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-C" data-lang="C">int main_menu_item; /* example: variable to keep track of selected item */

UINT main_menu_event_handler(GX_WINDOW *main_screen, GX_EVENT *event_ptr)
{
    UINT status = GX_SUCCESS;

    switch(event_ptr-&gt;gx_event_type)
    {
    /* this is an example for catching events from a child button */
    case GX_SIGNAL(IDB_CHILD_BUTTON, GX_EVENT_CLICKED):
        /* insert your button handler code here */
        break;

    case GX_EVENT_SHOW:
        /* add functionality to the show event handler */
        /* first, do default processing */
        status = gx_window_event_process(main_screen, event_ptr); /* note 1 */

        /* now add my own processing */
        main_menu_item = 0;
        break;

    default:
        /* pass all other events to base processing function */
        status = gx_window_event_process(main_screen, event_ptr); /* note 1 */
        break;
    }
    return status;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the example above, it is important to notice that for system events
like <strong>GX_EVENT_SHOW</strong> (events generated internally to notify a widget of a
status change), the application must pass those events to the base
widget event processing function to insure that the normal processing
occurs. The application can then add additional logic as desired. All
events that are not handled by the application (the default case above)
should also be passed to the base event processing function. Since this
example was for a top-level screen based on <strong>GX_WINDOW</strong>, the default
event processing function is gx_window_event_process.</p>
</div>
</div>
<div class="sect2">
<h3 id="_drawing_function">Drawing Function</h3>
<div class="paragraph">
<p>All widget drawing is performed separately from the event handling. This
is more efficient because drawing is usually expensive in terms of CPU
cycles. By implementing a deferred drawing algorithm, all of the
outstanding events and associated display changes can be completed
before any drawing is done, thus eliminating wasted drawing. Similar to
event processing, there is a default widget drawing function for most
widgets, named <strong><em>gx</em>&lt;widget-type&gt;_draw_</strong>, where xxx is the widget type. In
most cases, the application won&#8217;t need to worry about the drawing
function of any given widget. However, in situations where the
application requires custom or supplemental drawing, the application may
override the default drawing function with its own via the GUIX API
<strong><em>gx_widget_draw_set</em></strong>. This function allows the application to
provide its own customized drawing function for any widget. This further
allows the application to define entire new widget types.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Application drawing functions can take advantage (i.e., not duplicate the coding) of the default drawing by simply calling it directly from the overridden drawing function.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Widget drawing is called exclusively from the context of the internal
GUIX system thread. In this way, the timing and stack requirements to
perform the drawing only apply to the GUIX thread.</p>
</div>
</div>
<div class="sect2">
<h3 id="_implementing_custom_drawing_example">Implementing Custom Drawing (example)</h3>
<div class="paragraph">
<p>The drawing function for any widget is referenced through an indirect
function pointer which is a member of the GX_WIDGET control block. If
you use GUIX Studio to define your widget, you can install your own
function pointer simply by typing the name of your function in the
"Drawing Function" parameter of the widget properties, and Studio will
install your function pointer for you when the widget is created. If you
create the widget in your application code, you must use the
<strong><em>gx_widget_draw_set</em></strong> API function to install your custom drawing
function after the widget has been created.</p>
</div>
<div class="paragraph">
<p>For this example, let&#8217;s assume that you want to customize the appearance
of a button. The button will look very much like a <strong>GX_TEXT_BUTTON</strong>, but
we will add drawing a small green "LED_ON" bitmap in the middle-right
portion of the button when the button is pressed, and small "LED_OFF"
bitmap when the button is not pressed. We want to create a button that
looks like the illustrations below.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="./media/guix/image4.jpg" alt="Screenshot of the green button for On."></span> custom button "on"</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="./media/guix/image5.jpg" alt="Screenshot of the red button for Off."></span> custom button "off"</p>
</div>
<div class="paragraph">
<p>In this case, we would write a button drawing function that looks
something like the following.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-C" data-lang="C">UINT my_button_draw(GX_TEXT_BUTTON *button)
{
    GX_PIXELMAP *map;
    ULONG button_style;
    INT xpos;
    INT ypos;

    /* first, do the normal text button drawing */
    gx_text_button_draw(button);

    /* now add our extra pixelmap */

    gx_widget_style_get(button, &amp;button_style);

    if (button_style &amp; GX_STYLE_BUTTON_PUSHED)
    {
        /* use the ON pixelmap */
        gx_context_pixelmap_get(GX_PIXELMAP_ID_LED_ON, &amp;map);
    }
    else
    {
        /* use the OFF pixelmap */
        gx_context_pixelmap_get(GX_PIXELMAP_ID_LED_OFF, &amp;map);
    }
    if (map)
    {
        /* draw it 20 pixels in from right edge */
        xpos = button-&gt;gx_widget_size.gx_rectangle_right;
        xpos -= map-&gt;gx_pixelmap_width + 20;

        /* and draw 10 pixels from the top edge */
        ypos = button-&gt;gx_widget_size.gx_rectangle_top + 10;

        /* draw the extra pixelmap on top of the button */
        gx_canvas_pixelmap_draw(xpos, ypos, map);
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_drawing_context_component">GUIX Drawing Context Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The drawing context is created dynamically, at runtime, as GUIX performs
each canvas refresh operation. The drawing context ties together the
canvas, screen driver, and brush being used to perform the current
drawing operations.</p>
</div>
<div class="paragraph">
<p>The drawing context is defined by the <strong>GX_DRAW_CONTEXT</strong> structure.
This structure contains variables that define the clipping and view of
the current drawing operation, define the current canvas, and define the
current screen driver in use. The <strong>GX_DRAW_CONTEXT</strong> structure also holds the brush being used for
drawing. The draw context brush is the member that you will work
directly with in your custom drawing functions. The brush structure is
defined as shown in the code below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-C" data-lang="C">typedef struct GX_BRUSH_STRUCT
{
    GX_PIXELMAP *gx_brush_pixelmap;
    GX_FONT     *gx_brush_font;
    ULONG        gx_brush_line_pattern;
    ULONG        gx_brush_pattern_mask;
    GX_COLOR     gx_brush_fill_color;
    GX_COLOR     gx_brush_line_color;
    UINT         gx_brush_style;
    GX_VALUE     gx_brush_width;
    UCHAR        gx_brush_alpha;
} GX_BRUSH;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <strong>gx_brush_pixelmap</strong> field defines a pixelmap to use for rectangle
and polygon fills. This member is not used unless the
<strong>gx_brush_style</strong> is includes the <strong>GX_BRUSH_PIXELMAP</strong> style.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_brush_font</strong> member defines the font used for text drawing.
The <strong>gx_brush_line_pattern</strong> member defines the pattern used for
dashed lines.
The <strong>gx_brush_style</strong> member is a set of style flags that can be
OR&#8217;d together to fully define the brush attributes. The available
brush style flags include the following.</p>
</div>
<div class="paragraph">
<p><strong>GX_BRUSH_OUTLINE</strong><br>
<strong>GX_BRUSH_SOLID_FILL</strong><br>
<strong>GX_BRUSH_PIXELMAP_FILL</strong><br>
<strong>GX_BRUSH_ALIAS</strong><br>
<strong>GX_BRUSH_UNDERLINE</strong><br>
<strong>GX_BRUSH_ROUND</strong></p>
</div>
<div class="paragraph">
<p>The <strong>gx_brush_width</strong> member defines the line with for line
drawing, or the outline width for outlined shape drawing.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_brush_line_color</strong> member defines the foreground color for
line drawing and for text drawing.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_brush_fill_color</strong> member defines the solid fill color
used for shape filling. The GUIX context component provides a set of
APIs designed to make it very easy to modify the current brush within
the active context. These APIs include <strong>gx_context_brush_define</strong>,
<strong>gx_context_line_color_set</strong>,
<strong>gx_context_fill_color_set</strong>, <strong>gx_context_font_set</strong>, and
many others.</p>
</div>
<div class="paragraph">
<p>The draw context of a parent object is inherited by the objects
children. Actually, a clone of the parent drawing context is inherited
by the child objects when their drawing functions are invoked. The child
can modify the context without affecting the parent drawing, but it can
also inherit information from the parent such as brush color and style
if desired.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_window_component">GUIX Window Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The window component is responsible for all window processing in GUIX. A
GUIX window is fundamentally a distinct display area that may contain
one or more child widgets. In GUIX, the window is actually just a
special form of the fundamental widget object.</p>
</div>
<div class="paragraph">
<p>GUIX windows are implemented in an object oriented manner with full
support of inheritance. This is accomplished using ANSI C, which results
in the smallest possible memory and processing requirements.</p>
</div>
<div class="paragraph">
<p>GUIX windows extend the functionality of the GUIX widget primarily by
adding support for horizontal and vertical scrolling. GUIX window
objects can automatically create and display scroll bars and respond to
scroll bar input. Movable windows also have built in event handling to
allow the window to be moved or dragged based on pen input events.
Finally, GUIX window responds to receiving input focus by moving the
window to the front of the window Z-order.</p>
</div>
<div class="paragraph">
<p>GUIX window maintains the concept of <em>client area</em>, which is the
inner portion of the window once the window borders and non-client
objects such as scrollbars are removed from the available area. Client
area child widgets are clipped to the window client area, while
non-client children such as scroll bars are allowed to draw outside of
the client area, but are still clipped to the window outer dimensions.</p>
</div>
<div class="paragraph">
<p>Windows are maintained in a parent-child manner, where the children
inherit characteristics from their parent. Children windows may have
their own child windows, again inheriting various characteristics from
the parent. The characteristics of any window may be explicitly
redefined via various GUIX API calls.</p>
</div>
<div class="sect2">
<h3 id="_window_creation">Window Creation</h3>
<div class="paragraph">
<p>A window object can be created during initialization or anytime during
the execution of application threads. There is no limit on the number of
window objects that can be created by an application. There is also no
limit on the number of children any window may have.</p>
</div>
</div>
<div class="sect2">
<h3 id="_window_control_block">Window Control Block</h3>
<div class="paragraph">
<p>The characteristics of each window object are found in its control block
<strong>GX_WINDOW</strong> and are defined in <strong><em>gx_api.h</em></strong>. The memory required
for a window object is provided by the application and can be located
anywhere in memory. However, it is most common to make the window object
control block a global structure by defining it outside the scope of any
function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_root_window_2">Root Window</h3>
<div class="paragraph">
<p>GUIX requires what is called a root window for each canvas. The root
window is borderless and has the same dimensions as the canvas to which
it is attached. It is used primarily as a container for all first-level
widgets and windows. The root window is typically created by the
application via the API function <strong><em>gx_window_root_create</em></strong>, shortly after
the creation of the screen and canvas. If you use the Studio generated
function gx_studio_display_configure, the address of the root window
can be returned in the location passed as the last parameter to this
function.</p>
</div>
<div class="paragraph">
<p>A root window defaults to being un-moveable, and in the simplest case
the root window is the size of the canvas. The root window in effect
draws the display background, so to change the display background color
or to display background wallpaper you would assign a color or wallpaper
to the root window.</p>
</div>
<div class="paragraph">
<p>If a root window is moveable, it moves not by changing its position on
the canvas as a child window would do, but by moving the canvas itself.
This feature allows the GUIX root window to leverage hardware that
supports multiple frame buffers with hardware offset registers.</p>
</div>
</div>
<div class="sect2">
<h3 id="_background">Background</h3>
<div class="paragraph">
<p>Window backgrounds are either solid colors or bitmap images. There is a
default window background at the system level which provides the default
for the initial set of windows. Of course, any window background can be
changed via the GUIX API.</p>
</div>
<div class="paragraph">
<p>To change the solid color background of a window, use the
<strong><em>gx_widget_fill_color_set</em></strong> API. To assign a background
wallpaper to a window, use the <strong><em>gx_window_wallpaper_set</em></strong> API.</p>
</div>
</div>
<div class="sect2">
<h3 id="_scrolling">Scrolling</h3>
<div class="paragraph">
<p>GUIX supports standard window scrolling when area required to display
the window children exceeds the current size of the window&#8201;&#8212;&#8201;horizontally and/or vertically. To enable scrolling, the application
must create the desired scroll bars and attach them to the window.</p>
</div>
<div class="paragraph">
<p>The GUIX window component provides a default scrolling implementation
based on the size of the window client area and the extent of the all
child widgets. Applications can also provide their own scrolling
implementation and interpretation by overriding the
<strong><em>gx_window_scroll_info_get</em></strong> function for a particular window.</p>
</div>
</div>
<div class="sect2">
<h3 id="_event_notification_2">Event Notification</h3>
<div class="paragraph">
<p>The default window event processing function differs from the GX_WIDGET
event processing primarily in the handling of scrolling and sizing
events. GX_WINDOW provided default handlers for scrolling and sizing
events.</p>
</div>
<div class="paragraph">
<p>The application can also add its own custom events, starting numerically
after the constant <strong>GX_FIRST_APP_EVENT</strong>. All event numbers after
this constant are reserved for the application&#8217;s use. Of course, the
application&#8217;s window event handler must have processing for such
application events.</p>
</div>
</div>
<div class="sect2">
<h3 id="_event_processing_3">Event Processing</h3>
<div class="paragraph">
<p>Just like all other widget types, there is a default window event
processing function for every window, named <strong><em>gx_window_event_process</em></strong>. You will usually override this event
handling function with your own event handler in the windows that you
create. This is how you will respond to events and take action based on
events generated by the window child controls.</p>
</div>
<div class="paragraph">
<p>It is important to remember to invoke the base
<strong><em>gx_window_event_process</em></strong> function for GUIX system events if you
override that event handler, to allow the default event handling to
occur in addition to whatever action you are adding to the event
handler. For example if you provide a custom handler for the
<strong>GX_EVENT_SHOW</strong> event, and do not pass this event to
<strong><em>gx_window_event_process</em></strong>, your window will never become visible.
To provide a custom event handler for a window, use the
<strong><em>gx_widget_event_process_set</em></strong> function to define the address of
your event handler. This function overrides the default event processing
function with the event function processing function specified in the
API.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Application event processing
functions can take advantage (i.e., not duplicate the processing) of
the default processing by simply calling the default
<strong><em>gx_window_event_process</em></strong> directly.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Event processing is called exclusively from the context of the internal
GUIX system thread. In this way, the stack requirements to process the
event handling only applies to the GUIX thread.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_image_reader_component">GUIX Image Reader Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The image reader component provides utilities and API functions to
decompress raw compressed images to GUIX pixelmap format. JPEG and PNG
format raw image data are supported, with additional formats reserved
for future releases.</p>
</div>
<div class="paragraph">
<p>Note that for the vast majority of GUIX applications, the GUIX Image
Reader component is not required. Most applications rely on the GUIX
Studio application to convert JPEG and PNG format graphics assets into
GUIX compatible <strong>GX_PIXELMAP</strong> resources. The GUIX image reader component
is utilized when the raw graphics assets are known only at runtime, or
when the system storage constraints prevent storing resources in
<strong>GX_PIXELMAP</strong> format. JPEG and PNG format image data is generally more
compact than <strong>GX_PIXELMAP</strong> format, however there is considerable runtime
overhead associated with performing decompression and color space
conversion of these image types dynamically.</p>
</div>
<div class="paragraph">
<p>If raw format JPEG or PNG images are passed to the
gx_canvas_pixelmap_draw API function, GUIX dynamically decompresses
and draws the JPEG or PNG data. Note that this will have a significant
negative impact on runtime drawing speed, and passing RAW format image
data to the gx_canvas_pixelmap_draw function is not recommended
unless you are using a hardware target that supports hardware assisted
JPEG or PNG decompression.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Passing raw JPEG or PNG formatted
images to the gx_canvas_pixelmap_draw API incurs significant
runtime overhead for most target hardware.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>As an alternative, raw JPEG and PNG data may be converted to
GX_PIXELMAP format at runtime using the Image Reader component.
Pixelmaps produced in this way can be used and drawn just like pixelmaps
produced by Studio and contained within your resource file. This allows
your application to perform the image decompression, dithering, and
color space conversion one time (usually during program startup) rather
than performing these operations each time the image is drawn.</p>
</div>
<div class="paragraph">
<p>The Image Reader component functions include:</p>
</div>
<div class="paragraph">
<p><strong><em>gx_image_reader_create</em></strong><br>
<strong><em>gx_image_reader_palette_set</em></strong><br>
<strong><em>gx_image_reader_start</em></strong></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_animation_component">GUIX Animation Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The GUIX Animation component is a set of functions and services used to
automate screen and widget transition automations. The GUIX Animation
component supports fading in, fading out, and movement or slide type
animations of any widget type.</p>
</div>
<div class="paragraph">
<p>Fade type animations can be supported either by varying the fading
widget(s) internal alpha value (if <strong>GX_BRUSH_ALPHA_SUPPORT</strong> is
enabled), or by drawing any collection of widgets to a separate memory
canvas when is then blended with the background. For hardware targets
that support multiple hardware graphics layers, support for smooth
fading effects is best accomplished using this canvas blending approach,
often with very little core CPU bandwidth required. For hardware targets
that do not support multiple graphics layers, blending using the GUIX
brush alpha value is supported when running at 16 bpp and higher color
depths.</p>
</div>
<div class="paragraph">
<p>If an animation should use a separate drawing canvas, the GUIX Animation
component provides the API service gx_animation_canvas_define for
this purpose. Other animation types do not require a separate canvas,
but they will utilize it if it is available. This makes the best
possible use of any underlying hardware support for multiple hardware
surfaces.</p>
</div>
<div class="paragraph">
<p>The variables controlling an animation are defined by two control
blocks. First, the <strong>GX_ANIMATION</strong> control block which defines the
animation controller. The animation controller is the driving engine
that executes the animation sequence you define. A single animation
controller can be re-used many times to run many different animation
sequences. If you need to run multiple animation sequences
simultaneously, you can create multiple <strong>GX_ANIMATION</strong> animation
controllers.</p>
</div>
<div class="paragraph">
<p>The GUIX system component can provide a re-usable block of <strong>GX_ANIMATION</strong>
control structures, which can be requested by the application when and
animation is needed and are automatically returned to the system pool
when the animation sequence is completed. This frees the application
from statically defining a <strong>GX_ANIMATION</strong> structure for every animation that might be implemented. The size of
this pool of <strong>GX_ANIMATION</strong> structures is defined by the constant <strong>GX_ANIMATION_POOL_SIZE</strong>, which defaults to 6, meaning that by default
6 simultaneous animations can be allocated from the system pool. This
constant can of course be re-defined in the gx_user.h header file is
more simultaneous animations are required. If
<strong>GX_ANIMATION_POOL_SIZE</strong> is set to zero, then the GUIX system component does not provide an animation pool or related services.</p>
</div>
<div class="paragraph">
<p>The second control block or structure used to define an animation is the
<strong>GX_ANIMATION_INFO</strong> structure. This structure is used to define one
particular animation sequence. You pass this information structure to
your animation controller to initiate an animation sequence using the
gx_animation_start API service. The <strong>GX_ANIMATION_INFO</strong> structure
contains the following fields:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-C" data-lang="C">typedef struct GX_ANIMATION_INFO_STRUCT
{
    GX_WIDGET *gx_animation_target;
    GX_WIDGET *gx_animation_parent;
    GX_WIDGET *gx_animation_screen_list;
    USHORT gx_animation_style;
    USHORT gx_animation_id;
    USHORT gx_animation_start_delay;
    USHORT gx_animation_frame_interval;
    GX_POINT gx_animation_start_position;
    GX_POINT gx_animation_end_position;
    GX_UBYTE gx_animation_start_alpha;
    GX_UBYTE gx_animation_end_alpha;
    GX_UBYTE gx_animation_steps;
} GX_ANIMATION_INFO;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_target</strong> member defines the target widget that the
animation controller will act upon.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_parent</strong> member defines the parent widget, if any,
to which the target widget will be attached when the animation sequence
is complete. The gx_animation_parent is also the recipient of the
GX_ANIMATION_COMPLETE event that is generated when an animation is
completed.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_screen_list</strong> member defines a widget list for
pen-input-driven screen slide animations. The widget list should be
terminated with GX_NULL pointer, and each widget in the list should
have the same x,y dimensions as the gx_animation_parent.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_style</strong> is a bitmask defining the type of animation
to be performed and associated options. The animation style flags
include the following.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Animation&nbsp;Style&nbsp;Flag</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_TRANSLATE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request a slide or fade type animation.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_SCREEN_DRAG</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request a pen-input driven screen drag animation.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The following flags can be used in combination with <strong>SCREEN_DRAG</strong> type
animations.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Screen&nbsp;Drag&nbsp;Flags</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_WRAP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The screen list should wrap from end back to start.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_HORIZONTAL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Screen drag allowed in horizontal direction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_VERTICAL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Screen drag allowed in vertical direction.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The following flag can be used in combination with translate animations.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Translate&nbsp;Animations&nbsp;Flags</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_DETACH</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detach the animation target from the animation parent when the animation is completed. If the target was dynamically allocated and created by the GUIX Studio generated automated event handling, the target will be deleted after it is detached.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_TRANSLATE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Animation types are timer driven animations. The application defines the starting and ending position and starting and ending alpha value for the target widget, and the animation manager creates a timer to serve and as the driving force to execute the animation.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GX_ANIMATION_SCREEN_DRAG</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Differs from the <strong>TRANSLATE</strong> animations in that this animation type is driven by pen input events. This animation type tracks along with the touch screen input to swipe the target widget as the user drags a pen or stylus across the input touch screen. To utilize this type of animation, the application should call the <strong><em>gx_animation_drag_enable</em></strong> API to enable this animation.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The <strong>gx_animation_id</strong> value is passed back to the animation parent in the event.gx_event_sender field of the <strong>GX_ANIMATION_COMPLETE</strong> event. This value is used by the animation parent to determine which of possibly several child animations is reporting completion. This value can be 0, and an animation with ID value 0 will not generate an <strong>ANIMATION_COMPLETE</strong> event at all.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_start_delay</strong> value is a GUIX tick count indicating the number of timer ticks to delay after <strong><em>gx_animation_start</em></strong> is called before actually executing the animation. The value can be 0 to start the animation immediately upon calling <strong><em>gx_animation_start</em></strong>.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_frame_interval</strong> field defines the number of GUIX timer ticks (a multiple of the underlying OS tick rate) to delay between each frame of the animation sequence. The minimum value is 1.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_start_position</strong> defines the top-left starting point for the target widget for translation animations.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_end_position</strong> defines the top-left ending position for the target widget for translation type animations.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_start_alpha</strong> field defines the starting canvas alpha value for translation type animations.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_end_alpha</strong> field defines the ending canvas alpha
value for translation type animations.</p>
</div>
<div class="paragraph">
<p>The <strong>gx_animation_steps</strong> field defines how many steps or frames the
controller should execute for translation animations. A larger number of
steps produces a smoother slide and/or fade appearance, but also
requires greater system bandwidth.</p>
</div>
<div class="paragraph">
<p>To implement animation effects in your application, you must first call
<strong><em>gx_animation_create</em></strong> to initialize your animation controller. If your
animation will be using a secondary canvas, initialize this canvas by
calling gx_animation_canvas_define. Next, you should initialize the
<strong>GX_ANIMATION_INFO</strong> structure to define the specific type of animation
to be performed and the other animation parameters. Finally, call
gx_animation_start to trigger the animation sequence.</p>
</div>
<div class="paragraph">
<p>When the animation controller completes an animation sequence, it sends
an <strong>GX_ANIMATION_COMPLETE</strong> event to the parent widget, allowing the any
desired cleanup of the animation canvas to be done at that time.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_guix_utility_component">GUIX Utility Component</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The utility component is responsible for all common utility functions in
GUIX. These are common functions that are useful utilities and can be
invoked from anywhere in the application or the internal GUIX code. The
utility component functions include the following.</p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_canvas_to_bmp</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_circle_point_get</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_alphamap_create</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_gradient_create</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_gradient_delete</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_ltoa</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_math_acos</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_math_asin</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_math_cos</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_math_sin</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_math_sqrt</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_pixelmap_resize</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_pixelmap_rotate</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_pixelmap_simple_rotate</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_center</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_center_find</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_combine</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_compare</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_define</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_overlap_detect</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_point_detect</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_resize</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_rectangle_shift</em></strong></p>
</div>
<div class="paragraph">
<p><strong><em>gx_utility_string_to_alphamap</em></strong></p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2025-02-07 08:25:21 UTC
</div>
</div>
</body>
</html>